Google Calendar MCP Server

Google Calendar MCP 服务

一个基于 TypeScript 的模型上下文协议（MCP）服务，可让 Claude Desktop 连接并与 Google Calendar 交互。

功能

• 将 Claude Desktop AI 连接到 Google Calendar 数据
• 使用 Google OAuth2 进行授权
• 获取日历列表和活动
• 创建、更新和删除日历活动
• 获取所有日历中的近期活动
• 安全地处理令牌
• 使用 TypeScript 并提供强类型支持

要求

• Node.js（v16 或更高版本）
• npm 或 yarn
• 拥有 Calendar 访问权限的 Google 账号
• Google OAuth2 凭据（用于 Cloud OAuth 方式）

安装

1. 克隆仓库

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

2. 安装依赖项

npm install
# or
yarn install

3. 配置环境变量

根据 .env.example 创建 .env 文件：

cp .env.example .env

然后编辑 .env 文件并填写配置：

# Authentication Method Configuration
# -----------------------------
# Two authentication methods are available:
# 1. google_cloud - Uses Google Cloud OAuth (requires Google Cloud project setup)
# 2. direct - Uses direct authentication (simpler, doesn't require Google Cloud project)

# Choose one of the following authentication methods:
# AUTH_METHOD=google_cloud
AUTH_METHOD=direct

# Server Configuration
# -------------------
PORT=3000
NODE_ENV=development

# Google Calendar API (required only if AUTH_METHOD=google_cloud)
# --------------------------------------------------------------
# These credentials require a Google Cloud Platform project with Google Calendar API enabled
# You'll need to create OAuth credentials and configure the redirect URI in Google Cloud Console
GOOGLE_CLIENT_ID=your_google_client_id
GOOGLE_CLIENT_SECRET=your_google_client_secret
GOOGLE_REDIRECT_URI=http://localhost:3000/auth/callback

# MCP Configuration
# ----------------
MCP_SERVER_ID=google-calendar-mcp
MCP_SERVER_NAME=Google Calendar Integration
MCP_SERVER_DESCRIPTION=Retrieves and manages Google Calendar events

身份验证方式

此 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 更改其身份验证要求，此方式可能会停止工作。

运行服务

开发模式

# Start the development server with hot reloading
npm run dev
# or
yarn dev

生产模式

# Build the TypeScript code
npm run build
# or
yarn build

# Start the production server
npm run start
# or
yarn start

配置 Claude 以集成 MCP

关于 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 服务：

   # Development mode
   npm run dev
   
   # OR Production mode (after building)
   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，即可用于开发和测试：

# Using curl
curl -X POST http://localhost:3000/auth/direct \
  -H "Content-Type: application/json" \
  -d '{"email":"[email protected]","password":"your_password"}'  

# Or with 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": "Google Calendar MCP server using npx"
        }
      }
    }
   

3. 保存文件并重启 Claude Desktop

注意：此方法需要手动编辑配置文件，请谨慎使用。进行任何更改前，请务必备份设置文件。

验证连接

• 向 Claude 提出一个简单的日历相关问题，例如“我今天有哪些活动？”
• 如果 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 执行各种日历操作：

# View your schedule
What events do I have today?
What's on my calendar for next week?
Show me my meetings for tomorrow afternoon.

# Create events
Schedule a team meeting next Monday at 10 AM for 1 hour.
Add a doctor's appointment on Friday at 2 PM.
Create a recurring weekly check-in every Wednesday at 9 AM.

# Modify events
Reschedule my 3 PM meeting to 4 PM.
Move tomorrow's lunch meeting to Thursday.
Cancel my dentist appointment.

# Find available times
When am I free tomorrow for a 2-hour meeting?
Do I have any conflicts next Tuesday morning?
Find me an open 30-minute slot this week for a quick call.

测试

# Run tests
npm test
# or
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 使用示例

以下是使用 Claude Desktop 调用此 MCP 服务的示例：

1. 获取即将发生的活动

Claude, what are my upcoming calendar events for the next week?

Claude 会查询 MCP 服务并返回你的即将发生的活动列表。

2. 创建新活动

Claude, please schedule a meeting with John Doe about the project proposal for tomorrow at 2:00 PM, lasting for 1 hour.

Claude 会根据你的请求创建新的日历活动。

3. 查找日程冲突

Claude, do I have any scheduling conflicts next Monday between 10 AM and 3 PM?

Claude 会检查该时间段内的日历，并告知你是否有现存活动。

4. 重新安排活动

Claude, I need to reschedule my doctor's appointment on Thursday to Friday at the same time.

Claude 会找到该活动，并将其更新为新的日期。

5. 设置定期会议

Claude, please create a weekly team standup meeting every Monday at 9:00 AM starting next week.

Claude 会创建定期日历活动。

6. 查找空闲时段

Claude, when am I free for a 2-hour meeting with the design team this week?

Claude 会分析你的日历，并推荐可用时段。

Docker 部署

项目包含 Docker 配置，方便部署：

# Build and run with 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 许可，详情请参阅 LICENSE 文件。