Google Calendar AutoAuth MCP Server

Google Calendar AutoAuth MCP Server

一个用于在 Claude Desktop 中集成 Google Calendar 并支持自动身份验证的模型上下文协议（MCP）服务。该服务支持 AI 助手通过自然语言交互管理 Google Calendar。

功能

• 创建日历事件，并设置标题、描述、地点和参与者
• 更新现有日历事件
• 删除日历事件
• 获取事件详情
• 列出指定时间范围内的事件
• 按关键词搜索事件
• 列出所有可用日历
• 支持自然语言日期和时间输入（例如“明天下午 2 点”“下周一”）
• 完全集成 Google Calendar API
• 简单的 OAuth2 身份验证流程，并自动启动浏览器
• 支持桌面应用和 Web 应用凭据
• 便于使用的全局凭据存储

安装与身份验证

通过 Smithery 安装

要通过 Smithery 自动为 Claude Desktop 安装 Google Calendar Integration Server：

npx -y @smithery/cli install @falgom4/calendar-mcp --client claude

手动安装

1. 创建 Google Cloud 项目并获取凭据：

   a. 创建 Google Cloud 项目：

   • 前往 Google Cloud Console
   • 创建新项目或选择现有项目
   • 为项目启用 Google Calendar API

   b. 创建 OAuth 2.0 凭据：

   • 前往“APIs & Services” > “Credentials”
   • 点击“Create Credentials” > “OAuth client ID”
   • 将“Desktop app”或“Web application”选为应用类型
   • 输入名称并点击“Create”
   • 对于 Web application，将 http://localhost:3000/oauth2callback 添加到获准的重定向 URI
   • 下载客户端 OAuth 密钥的 JSON 文件
   • 将密钥文件重命名为 gcp-oauth.keys.json

2. 运行身份验证：

   你可以通过以下两种方式进行身份验证：

   a. 全局身份验证（推荐）：

   # First time: Place gcp-oauth.keys.json in your home directory's .calendar-mcp folder
   mkdir -p ~/.calendar-mcp
   mv gcp-oauth.keys.json ~/.calendar-mcp/
   
   # Run authentication from anywhere
   npx @nchufa/calendar auth
   

   b. 本地身份验证：

   # Place gcp-oauth.keys.json in your current directory
   # The file will be automatically copied to global config
   npx @nchufa/calendar auth
   

   身份验证过程将会：

   • 在当前目录或 ~/.calendar-mcp/ 中查找 gcp-oauth.keys.json
   • 如果文件位于当前目录，则将其复制到 ~/.calendar-mcp/
   • 打开默认浏览器进行 Google 身份验证
   • 将凭据保存为 ~/.calendar-mcp/credentials.json

   注意：

   • 身份验证成功后，凭据会全局存储在 ~/.calendar-mcp/ 中，可从任意目录使用
   • 支持桌面应用和 Web 应用凭据
   • 对于 Web 应用凭据，请确保将 http://localhost:3000/oauth2callback 添加到获准的重定向 URI

3. 在 Claude Desktop 中配置：

将以下内容添加到 Claude Desktop 配置文件中：

{
  "mcpServers": {
    "calendar": {
      "command": "npx",
      "args": [
        "@nchufa/calendar"
      ]
    }
  }
}

可用工具

该服务提供以下工具，可通过 Claude Desktop 使用：

1. 创建事件（create_event）

创建新的日历事件。

{
  "summary": "Team Meeting",
  "description": "Weekly team sync to discuss project progress",
  "location": "Conference Room A",
  "start": "2025-04-01T14:00:00",
  "end": "2025-04-01T15:00:00",
  "attendees": ["[email protected]", "[email protected]"],
  "reminders": {
    "useDefault": false,
    "overrides": [
      {
        "method": "email",
        "minutes": 30
      },
      {
        "method": "popup",
        "minutes": 10
      }
    ]
  }
}

也支持自然语言日期和时间：

{
  "summary": "Coffee with John",
  "location": "Starbucks Downtown",
  "start": "tomorrow at 2:30pm",
  "end": "tomorrow at 3:30pm"
}

2. 获取事件（get_event）

获取特定日历事件的详情。

{
  "eventId": "abc123xyz456",
  "calendarId": "primary"
}

3. 更新事件（update_event）

更新现有日历事件。

{
  "eventId": "abc123xyz456",
  "summary": "Updated Meeting Title",
  "location": "New Location",
  "start": "2025-04-01T15:00:00",
  "end": "2025-04-01T16:00:00"
}

4. 删除事件（delete_event）

删除日历事件。

{
  "eventId": "abc123xyz456",
  "calendarId": "primary"
}

5. 列出事件（list_events）

列出指定时间范围内的日历事件。

{
  "calendarId": "primary",
  "timeMin": "2025-04-01T00:00:00",
  "timeMax": "2025-04-07T23:59:59",
  "maxResults": 10,
  "orderBy": "startTime"
}

6. 搜索事件（search_events）

搜索与查询匹配的事件。

{
  "query": "meeting",
  "calendarId": "primary",
  "timeMin": "2025-04-01T00:00:00",
  "maxResults": 5
}

7. 列出日历（list_calendars）

列出所有可用日历。

{}

自然语言日期/时间支持

服务器支持多种自然语言日期和时间格式：

• 特定日期：“2025-04-01T14:00:00”（ISO 格式）
• 简单引用：“today”、“tomorrow”、“now”
• 相对时间：“2 hours later”、“3 days later”
• 星期引用：“next monday”、“next tuesday”
• 组合格式：“tomorrow at 2pm”、“monday at 15:30”

这样一来，您就可以使用自然语言指令轻松创建和更新事件。

安全提示

• OAuth 凭据安全地存储在本地环境中（~/.calendar-mcp/）
• 服务器使用离线访问来维持持久身份验证
• 切勿分享凭据，也不要将凭据提交到版本控制系统
• 定期在 Google 帐户设置中检查并撤销不再使用的访问权限

故障排除

1. 未找到 OAuth 密钥

   • 确保 gcp-oauth.keys.json 位于当前目录或 ~/.calendar-mcp/ 中
   • 检查文件权限

2. 凭据格式无效

   • 确保 OAuth 密钥文件包含 web 或 installed 凭据
   • 对于 Web 应用，请确认重定向 URI 配置正确

3. 端口已被占用

   • 如果端口 3000 已被占用，请在运行身份验证前释放该端口
   • 您可以查找并停止占用该端口的进程

贡献

欢迎贡献！欢迎提交 Pull Request。

许可证

MIT

致谢

特别感谢 GongRzhe 及其 Calendar-Autoauth-MCP-Server 项目，该项目为本实现奠定了基础。

支持

如果您遇到任何问题或有疑问，请在 GitHub 仓库中提交 issue。