Google 日历 MCP 服务器

这是一个提供与 Google 日历集成的 Model Context Protocol (MCP) 服务器，适用于像 Claude 这样的AI助手。

功能

• 多日历支持：同时列出多个日历中的事件
• 事件管理：创建、更新、删除和搜索日历事件
• 重复事件：高级修改重复事件的能力
• 空闲/忙碌查询：检查日历上的可用性
• 智能调度：理解自然语言中的日期和时间
• 智能导入：从图片、PDF或网页链接中添加日历事件

快速开始

先决条件

1. 启用了日历API的Google云项目
2. OAuth 2.0凭证（桌面应用类型）

Google Cloud 设置

1. 访问Google Cloud 控制台
2. 创建一个新项目或选择现有项目。
3. 为您的项目启用Google 日历 API。确保在启用API之前从顶部栏选择了正确的项目。
4. 创建OAuth 2.0凭证：
   • 转到凭证
   • 点击“创建凭证” > “OAuth客户端ID”
   • 选择“用户数据”作为应用程序将访问的数据类型
   • 添加您的应用名称和联系信息
   • 添加以下作用域（可选）：
     • https://www.googleapis.com/auth/calendar.events 和 https://www.googleapis.com/auth/calendar
   • 选择“桌面应用”作为应用类型（重要！）
   • 保存认证密钥，您需要在下一步中将其路径添加到JSON中
   • 在Audience 屏幕下添加您的电子邮件地址作为测试用户
     • 注意：添加测试用户可能需要几分钟时间。OAuth同意界面不会让您继续操作直到测试用户传播完成。
     • 关于测试模式的注意事项：当应用处于测试模式时，认证令牌将在一周后过期并需要刷新（参见下面的重新认证部分）。

安装

选项1：使用npx（推荐）

在您的Claude Desktop配置中添加：

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

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

⚠️ 对于npx用户的重要提示：使用npx时，您必须通过环境变量GOOGLE_OAUTH_CREDENTIALS指定凭证文件路径。

选项2：本地安装

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
npm install
npm run build

然后使用本地路径或通过指定GOOGLE_OAUTH_CREDENTIALS环境变量来添加到Claude Desktop配置中。

选项3：Docker安装

git clone https://github.com/nspady/google-calendar-mcp.git
cd google-calendar-mcp
cp /path/to/your/gcp-oauth.keys.json .
docker compose up

查看Docker 部署指南以获取详细的配置选项，包括HTTP传输模式。

第一次运行

1. 启动Claude Desktop
2. 服务器会在首次使用时提示进行身份验证
3. 在浏览器中完成OAuth流程
4. 您现在可以使用日历功能了！

重新认证

如果您处于测试模式（默认），令牌将在7天后过期。如果您使用的是像Claude Desktop这样的客户端，它应该会打开一个浏览器窗口以自动重新认证。然而，如果遇到认证错误，您可以按照以下步骤解决：

对于npx用户：

export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json"
npx @cocal/google-calendar-mcp auth

对于本地安装：

npm run auth

为了避免每周重新认证，将您的应用发布到生产模式（无需验证）：

1. 转到Google Cloud Console → "APIs & Services" → "OAuth同意屏幕"
2. 点击“发布应用”并确认
3. 您的令牌将不再在7天后过期，但Google在连接到未验证的应用时会显示更严重的警告。

详见认证指南。

示例用法

除了预期的日历集成功能外，您还可以执行非常动态、多步骤的过程，如：

1. 跨日历可用性：

   请提供查看我的个人和工作日历本周的可用性。
   我正在寻找一个合适的时间与伦敦的人见面，持续1小时。
   

2. 从截图、图像和其他数据源添加事件：

   根据附带的截图将此事件添加到我的日历中。
   

   支持的图像格式：PNG、JPEG、GIF 图像可以包含事件详情，如日期、时间、地点和描述

3. 日历分析：

   这周我有哪些不是日常安排的事件？
   

4. 检查出席情况：

   明天哪些活动的参与者尚未接受邀请？
   

5. 自动协调事件：

   这里是一些别人给我的可用时间。{可用时间}
   查看提供的时间，并告诉我哪些在我的日历上是开放的。
   

可用工具

工具	描述
list-calendars	列出所有可用的日历
list-events	使用日期过滤列出事件
search-events	通过文本查询搜索事件
create-event	创建新的日历事件
update-event	更新现有事件
delete-event	删除事件
get-freebusy	检查日历上的可用性，包括外部日历
list-colors	列出可用的事件颜色

文档

• 认证设置 - 详细的Google Cloud设置
• 高级用法 - 多账户、批处理操作
• 部署指南 - HTTP传输、远程访问
• Docker指南 - Docker部署，包括stdio和HTTP模式
• OAuth验证 - 从测试模式迁移到生产模式
• 架构 - 技术架构概述
• 开发 - 贡献和测试
• 测试 - 单元和集成测试指南

配置

环境变量：

• GOOGLE_OAUTH_CREDENTIALS - OAuth凭证文件路径
• GOOGLE_CALENDAR_MCP_TOKEN_PATH - 自定义令牌存储位置（可选）

Claude Desktop 配置位置：

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

安全

• OAuth令牌安全地存储在系统配置目录中
• 凭证永远不会离开您的本地机器
• 所有日历操作都需要明确的用户同意

故障排除

1. 找不到OAuth凭证文件：

   • 对于npx用户：您必须通过GOOGLE_OAUTH_CREDENTIALS指定凭证文件路径
   • 验证文件路径是绝对路径且可访问

2. 认证错误：

   • 确保您的凭证文件包含桌面应用类型的凭证
   • 验证您的用户电子邮件已添加为Google Cloud OAuth同意屏幕中的测试用户
   • 尝试删除保存的令牌并重新认证
   • 检查是否有其他进程阻止了3000-3004端口

3. 构建错误：

   • 再次运行npm install && npm run build
   • 检查Node.js版本（使用LTS版本）
   • 删除build/目录并运行npm run build

4. 浏览器认证期间出现“出现问题”的页面

   • 按照以下步骤进行手动认证
   • 使用基于Chromium的浏览器打开认证URL。某些非Chromium浏览器可能不支持测试应用认证。

5. “用户速率限制超出”错误

   • 这通常发生在您的OAuth凭证缺少项目信息时
   • 确保您的gcp-oauth.keys.json文件包含project_id
   • 如需，从Google Cloud Console重新下载凭证
   • 文件应具有如下格式：{"installed": {"project_id": "your-project-id", ...}}

手动认证

用于重新认证或故障排除：

# 对于npx安装
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/credentials.json"
npx @cocal/google-calendar-mcp auth

# 对于本地安装
npm run auth

许可

MIT

支持

• GitHub Issues
• 文档