Google Calendar MCP 服务器

一个基于 TypeScript 的模型上下文协议 (MCP) 服务器，允许 Claude Desktop 连接到 Google Calendar 并与之交互。

功能

• 将 Claude Desktop AI 连接到 Google Calendar 数据
• 使用 Google OAuth2 进行授权
• 检索日历列表和事件
• 创建、更新和删除日历事件
• 获取所有日历中即将发生的事件
• 安全的令牌处理
• 具有强类型的 TypeScript

要求

• Node.js (v16 或更高版本)
• npm 或 yarn
• 具有日历访问权限的 Google 帐户
• Google OAuth2 凭据（用于 Cloud OAuth 方法）

安装

1. 克隆存储库

git clone https://github.com/Jackson88/google-calendar-mcp
cd google-calendar-mcp

2. 安装依赖项

npm install
# 或
yarn install

3. 配置环境变量

基于 .env.example 创建一个 .env 文件：

cp .env.example .env

然后使用您的配置编辑 .env 文件：

# 身份验证方法配置
# -----------------------------
# 两种身份验证方法可用：
# 1. google_cloud - 使用 Google Cloud OAuth（需要 Google Cloud 项目设置）
# 2. direct - 使用直接身份验证（更简单，不需要 Google Cloud 项目）

# 选择以下身份验证方法之一：
# AUTH_METHOD=google_cloud
AUTH_METHOD=direct

# 服务器配置
# -------------------
PORT=3000
NODE_ENV=development

# Google Calendar API（仅当 AUTH_METHOD=google_cloud 时才需要）
# --------------------------------------------------------------
# 这些凭据需要启用 Google Calendar API 的 Google Cloud Platform 项目
# 您需要在 Google Cloud Console 中创建 OAuth 凭据并配置重定向 URI
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

# MCP 配置
# ----------------
MCP_SERVER_ID=google-calendar-mcp
MCP_SERVER_NAME=Google Calendar Integration
MCP_SERVER_DESCRIPTION=检索和管理 Google Calendar 事件

身份验证方法

此 MCP 服务器支持两种身份验证方法：

1. Google Cloud OAuth（推荐）

这是推荐的也是最安全的方法。 它需要创建一个 Google Cloud 项目和 OAuth 凭据，但提供最佳的安全性和用户体验。

• 遵循 OAuth 2.0 最佳实践
• 无需直接处理用户凭据
• 对于生产用途最可靠

要设置 Google Cloud OAuth：

1. 转到 Google Cloud Console
2. 创建一个新项目
3. 启用 Google Calendar API
4. 创建 OAuth2 凭据（Web 应用程序类型）
5. 添加授权的重定向 URI：
   • 对于开发：http://localhost:3000/auth/callback
   • 对于生产：您的生产回调 URL

2. 直接身份验证（简化）

对于个人或开发用途，您可以使用简化的直接身份验证方法，该方法不需要 Google Cloud 设置。

• 使用直接 Google 帐户身份验证
• 设置更简单，但具有安全性和可靠性限制
• 最适合个人或开发用途

要使用直接身份验证，请在您的 .env 文件中设置以下内容：

AUTH_METHOD=direct

注意：直接身份验证可能受到 Google 安全策略的约束，如果 Google 更改其身份验证要求，则可能停止工作。

运行服务器

开发模式

# 启动具有热重载的开发服务器
npm run dev
# 或
yarn dev

生产模式

# 构建 TypeScript 代码
npm run build
# 或
yarn build

# 启动生产服务器
npm run start
# 或
yarn start

为 MCP 集成配置 Claude

关于 Claude 兼容性的重要说明

⚠️ 当前限制：截至 2025 年 4 月，Claude Desktop 可能对 MCP 连接的支持有限或没有。 测试表明，当前版本的 Claude Desktop 不连接到外部 MCP 服务器，无论使用哪种身份验证方法。 以下说明供将来参考，届时 Claude Desktop 将完全支持 MCP 服务器连接。

如果您收到一条错误消息，指出“我无法连接到任何外部服务器”，则表明您的 Claude Desktop 版本当前不支持外部 MCP 连接。 这是当前 Claude Desktop 实现的限制，而不是此 MCP 服务器的问题。

先决条件

1. 您必须在您的计算机上安装 Claude Desktop
2. Google Calendar MCP 服务器必须正在运行且可访问
3. 您的 Claude Desktop 版本必须支持 MCP 连接

运行服务器

您需要在要求 Claude 连接到 MCP 服务器之前手动启动它。 Claude Desktop 不会使用 npx 或任何其他命令为您运行服务器。

请按照以下步骤设置集成：

1. 启动 MCP 服务器：

   # 开发模式
   npm run dev
   
   # OR 生产模式 (构建后)
   npm run build
   npm run start
   

2. 使用 Google 进行身份验证（仅首次）：

   • 对于 Google Cloud OAuth：在您的浏览器中访问 http://localhost:3000/mcp/auth/url 并完成授权流程
   • 对于直接身份验证：使用 Postman 或 curl 等工具向 http://localhost:3000/auth/direct 发送带有您的凭据的 POST 请求

直接身份验证方法

此服务器支持两种使用 Google Calendar 的身份验证方法。 即使 Claude Desktop 连接尚不受支持，这两种方法都可以直接与服务器 API 一起使用。

1. Google Cloud OAuth（推荐）

这是使用标准 OAuth 流程的更安全的方法：

1. 在您的浏览器中访问 http://localhost:3000/mcp/auth/url
2. 完成 Google 授权过程
3. 您将被重定向回回调 URL

2. 直接身份验证

对于开发/测试，无需设置 Google Cloud：

# 使用 curl
curl -X POST http://localhost:3000/auth/direct \
  -H "Content-Type: application/json" \
  -d '{"email":"your.email@gmail.com","password":"your_password"}'  

# 或使用 cookies
curl -X POST http://localhost:3000/auth/direct \
  -H "Content-Type: application/json" \
  -d '{"cookies":"your_google_cookies"}'  

即使 Claude Desktop 连接尚不受支持，这些方法也允许您直接测试服务器功能。

配置 Claude Desktop 设置

需要配置 Claude Desktop 以识别和访问您的 MCP 服务器：

1. 找到您的 Claude Desktop 设置文件：

   • 在 macOS 上：~/Library/Application Support/Claude/claude_desktop_config.json
   • 在 Windows 上：%APPDATA%\Claude\claude_desktop_config.json

2. 将 MCP 服务器配置添加到设置文件：

   • 在文本编辑器中打开 settings.json 文件
   • 查找或创建 mcpServers 部分
   • 添加以下配置（根据需要进行调整）：

    {
      "mcpServers": {
        "google-calendar": {
          "command": "npx",
          "args": ["-y", "google-calendar-mcp"],
          "env": {
            "GOOGLE_CLIENT_ID": "<your-client-id>",
            "GOOGLE_CLIENT_SECRET": "<your-client-secret>",
            "GOOGLE_REDIRECT_URI": "http://localhost:3000/auth/callback"
          },
          "description": "使用 npx 的 Google Calendar MCP 服务器"
        }
      }
    }
   

3. 保存文件并重新启动 Claude Desktop

注意：此方法需要手动编辑配置文件，应谨慎使用。 在进行更改之前，始终备份设置文件。

验证连接

• 向 Claude 询问一个简单的与日历相关的问题，例如“我今天有什么活动？”
• 如果它回复您的日历信息，则连接正在工作

排除 Claude 连接故障

如果 Claude 无法连接到您的 MCP 服务器：

1. 检查 Claude 的响应： 如果连接有问题，Claude 通常会告诉您

2. 验证服务器 URL： 确保您已指定正确的 URL，包括 /mcp 路径

3. 检查服务器日志： 查看您的 MCP 服务器正在运行的控制台，查找任何错误消息

4. 重新启动两个应用程序： 有时重新启动 Claude Desktop 和 MCP 服务器都可以解决连接问题

5. 身份验证状态： 确保您已成功使用 Google 进行身份验证，然后再尝试使用连接

6. 联系 Anthropic 支持： 如果您收到一条消息，指出 Claude 无法连接到外部服务器，您可能需要联系 Anthropic 支持，了解您的 Claude Desktop 版本中 MCP 功能的可用性

Claude 命令参考

连接后，您可以要求 Claude 执行各种日历操作：

# 查看您的日程安排
我今天有什么活动？
下周我的日历上有什么？
告诉我明天下午的会议。

# 创建活动
安排下周一上午 10 点的团队会议，时长 1 小时。
在星期五下午 2 点添加一个医生预约。
创建每周三上午 9 点的定期每周签到。

# 修改活动
将我的下午 3 点的会议重新安排到下午 4 点。
将明天的午餐会议移到星期四。
取消我的牙医预约。

# 查找可用时间
我明天什么时候有空参加 2 小时的会议？
下周二上午我是否有任何冲突？
本周为我找一个 30 分钟的空闲时间段，以便快速通话。

测试

# 运行测试
npm test
# 或
yarn test

API 端点

服务器公开以下 MCP 端点：

身份验证

• GET /mcp/auth/url - 获取 Google OAuth2 授权 URL
• POST /mcp/auth/callback - 处理授权后的 OAuth2 回调
• POST /auth/direct - 使用 Google 帐户直接身份验证（当使用直接身份验证方法时）

日历

• GET /mcp/calendars - 获取可用日历列表

事件

• GET /mcp/events - 从特定日历获取事件
• GET /mcp/events/upcoming - 获取所有日历中即将发生的事件
• POST /mcp/events/create - 创建新的日历事件
• PUT /mcp/events/update - 更新现有日历事件
• DELETE /mcp/events/delete - 删除日历事件
• GET /mcp/events/detail - 获取特定事件的详细信息

服务器信息

• GET /mcp/info - 获取服务器信息和可用端点
• GET /health - 健康检查端点

与 Claude Desktop 的示例用法

以下是如何将此 MCP 服务器与 Claude Desktop 一起使用的一些示例：

1. 获取即将发生的事件

Claude，我下周有哪些即将发生的日历事件？

Claude 将查询 MCP 服务器并返回您的即将发生的事件列表。

2. 创建新事件

Claude，请安排明天下午 2:00 与 John Doe 举行关于项目提案的会议，时长 1 小时。

Claude 将根据您的请求创建一个新的日历事件。

3. 查找日程安排中的冲突

Claude，下周一上午 10 点到下午 3 点之间我是否有任何日程安排冲突？

Claude 将检查您在该时间段内的日历，并告知您任何现有事件。

4. 重新安排事件

Claude，我需要将我星期四的医生预约重新安排到星期五的同一时间。

Claude 将找到该事件并使用新日期更新它。

5. 设置定期会议

Claude，请从下周开始，每周一上午 9:00 创建一个每周团队站立会议。

Claude 将创建一个定期日历事件。

6. 查找空闲时间段

Claude，本周我什么时候有空与设计团队举行 2 小时的会议？

Claude 将分析您的日历并建议可用的时间段。

Docker 部署

该项目包括 Docker 配置，以便于部署：

# 使用 Docker Compose 构建和运行
docker-compose up -d

安全注意事项

• 此 MCP 服务器将身份验证令牌本地存储在文件中。 确保这些文件是安全的，并且没有提交到版本控制。
• 在生产环境中，考虑实施更安全的令牌存储方法。
• 服务器默认在生产模式下使用 HTTPS 进行安全通信。
• 当令牌过期时，会自动处理令牌刷新。

故障排除

身份验证问题

如果您遇到身份验证问题：

1. 确保您的凭据已在 .env 文件中正确配置
2. 检查重定向 URI 是否与 Google Cloud Console 中配置的完全匹配（对于 Cloud OAuth）
3. 确保 Google Cloud 项目中已启用 Google Calendar API（对于 Cloud OAuth）
4. 尝试清除令牌文件并重新进行身份验证

连接问题

如果 Claude Desktop 无法连接到 MCP 服务器：

1. 验证服务器是否正在运行并且可以在指定的 URL 访问
2. 检查防火墙设置以确保端口已打开
3. 确保服务器的端口与 Claude Desktop 尝试连接的端口匹配

日历访问问题

如果您在访问日历或事件时遇到问题：

1. 确保您已在身份验证流程中授予必要的权限
2. 检查您的 Google 帐户是否有权访问您尝试查看的日历
3. 验证正在使用的日历 ID 是否正确

贡献

欢迎贡献！ 请随时提交 Pull Request。

许可证

此项目已获得 MIT 许可证的许可 - 有关详细信息，请参阅 LICENSE 文件。