谷歌日历 MCP 服务器

一个模型背景协议(MCP)服务器,为克洛德等AI助手提供Google日历集成.

特征

• 多账户支助:连接多个Google账户(如工作,个人)并同时查询
• 多日历支持: 在单个请求中列出多个日历中的事件
• 交叉冲突: 检测日历组合中的重叠事件
• 事件管理: 创建、更新、删除并搜索日历事件
• 经常性事件: 经常性活动的高级修改能力
• 免费/ Busy 查询: 检查日历的可用性
• 智能排程: 日期和时间的自然语言理解
• 智能导入: 从图像、 PDF 或网络链接添加日历事件

快速启动

不想设立"谷歌云"项目?? 焦值 是一个在 Claude 在桌面和移动上工作的主机选项.

先决条件

1. 启用日历 API 的 Google Cloud 项目
2. OAuth 2.0 证书( Desktop app 类型)

谷歌云设置

1. 转到 谷歌云控台
2. 创建新工程或选择现有工程 .
3. 启用 谷歌日历 API 你的项目。 确保在启用 API 之前从上行选择正确的项目 .
4. 创建 OAuth 2. 0 证书 :
   • 转到证书
   • 点击“ 创建证书” > “ OAuth 客户端 ID”
   • 选择应用程序将访问的数据类型“ 用户数据 ”
   • 添加您的应用程序名称和联系人信息
   • 增加以下范围(可选):
     • https://www.googleapis.com/auth/calendar.events 财务报告和审定财务报表 https://www.googleapis.com/auth/calendar
   • 选择“ Desktop app”为应用程序类型( 重要 !)
   • 保存 Auth 密钥, 您需要在下一步将其路径添加到 JSON 中
   • 添加您的电子邮件地址作为测试用户 观众屏幕
     • 注:测试用户可能需要几分钟时间才能加入. OAuth 同意不会允许您在测试用户推广之前继续 .
     • 关于测试模式的注释: 当一个app在测试模式中时, 认证符将在1周后过期并需要刷新(见下文再认证部分) .

安装

备选案文1:与npx(建议使用)

添加到您的 Claude 桌面配置 :

马科斯数字 : ~/Library/Application Support/Claude/claude_desktop_config.json 窗口数字 : %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

然后使用本地路径或者通过指定路径添加到 Claude 桌面配置 GOOGLE_OAUTH_CREDENTIALS 环境变量.

备选办法3:安装嵌入器

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. 启动克洛德桌面
2. 请 Claude 使用 Google 日历 MCP 服务器认证 (例如"授权与谷歌日历"). 在使用任何日历工具之前,需要这一步骤——如果没有这一步骤,请求将失败 -32600 错误.
3. 完成浏览器中的 OAuth 流量
4. 你准备好使用日历特性了!

用克洛德密码? 同样的步骤适用——只是要求克洛德在使用任何日历工具之前,先从您的 CLI 会话中认证Google Calendar MCP 服务器.

重新校正

如果您处于测试模式( 默认) , 标志在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. 点击“ PUBLISH AP” 确认
3. 7天后你的标志就不再过期了 但Google会发出警告说 应用程序没有得到验证.

见 认证指南 详细情况.

服务账户认证( 可选)

服务账户带有自己的长寿密钥, 因此没有浏览器同意步骤 并且没有新鲜的纪念品过期。 这是发布 OAuth 应用程序的替代方案 当上面的每周重新校正是不切实际的——无头服务器,容器, CI,或者一个应用程序,你宁愿离开 在测试状态.

此日历用于

共享是授权访问的内容——服务账户是一个独立的身份,并看到 没有默认的. 无需全域授权 个人日历 大小写; 只有在您想要服务账户行事时才需要 作为 用户.

限制

• 无法邀请参与者 . API拒绝这一点 "服务账户不能 请无域-广域授权代表团出席者”其他一切 - 创建、更新、删除、搜索、自由/忙碌——正常工作.
• calendarId 必须明确. primary 指服务账户自己的, 空日历;通过日历地址(如. [email protected]相反.
• list-calendars 返回无. 与服务账户共享的日历不 显示于 calendarList 除非明确添加。 由 id 编辑的地址日历 .

设置

1. 在您的 Google Cloud 项目中创建服务账户和 JSON 密钥 :

   gcloud iam service-accounts create calendar-mcp --project=YOUR_PROJECT
   gcloud iam service-accounts keys create service-account.json \
     --iam-account=calendar-mcp@YOUR_PROJECT.iam.gserviceaccount.com
   

2. 在谷歌日历中, 打开 设置 / 您的日历 / 与特定人共享, (中文(简体) ), 添加服务账户的电子邮件和赠款 "改变事件"。 。 。 .

3. 将服务器指向密钥 :

   {
     "mcpServers": {
       "google-calendar": {
         "command": "npx",
         "args": ["@cocal/google-calendar-mcp"],
         "env": {
           "GOOGLE_SERVICE_ACCOUNT_KEY": "/path/to/service-account.json"
         }
       }
     }
   }
   

该密钥被其内容检测出( :"type": "service_account"而不是通过模式旗, 因此切换一个已有的安装是一个文件更改 。 有三件事需要咨询, 获得答案的第一个胜出者

1. GOOGLE_SERVICE_ACCOUNT_KEY ——明确要求服务账户模式. 若为 文件缺失, 无法读取, 或者没有服务账户密钥, 服务器 失败 开始 而不是回到OAuth 让你猜 为什么.
2. 此服务器自己的证书文件 —— 说 GOOGLE_OAUTH_CREDENTIALS 如果你设置它, 否则 gcp-oauth.keys.json。它按内容阅读,所以设置一个服务账户 键在该路径工作。 如果它持有普通的 OAuth 客户端证书,则解决 它:你有OAuth设置,第三步被跳过.
3. GOOGLE_APPLICATION_CREDENTIALS ——共享的Google变量,常被设定 用于无关的工具。 只有在该服务器没有证书文件时才咨询它 国家GOOGLE_OAUTH_CREDENTIALS 未设置和无法使用 gcp-oauth.keys.json),这样 它永远不会覆盖工作 OAuth 安装。 依赖默认值 gcp-oauth.keys.json 而文件丢失,则使用这个变量; 设置 GOOGLE_OAUTH_CREDENTIALS 明确排除这一点,因为一条明确的道路是: 不能读取失败启动而不是倒下. 有问题就警告你 关于,永远不会致命.

服务器记录它选择的证书, 以及它们来自哪里, 在每一个启动时. 设定 GOOGLE_SERVICE_ACCOUNT_SUBJECT 只有在您使用全域权限.

将密钥文件视为证书: 它不会过期 . chmod 600 让它远离 版本控件,如果曾经被曝光,则删除 Cloud Console 中的密钥.

管理多账户

连接多个Google账户并同时使用.

聊天( 建议): 使用 manage-accounts 从您的 AI 助手中直接添加、 列出或删除账户的工具 - 不需要终端。 见 认证指南 详细情况.

CLI: 爱丽丝 对于初始设置, 使用 npm run account auth <nickname> (例如, npm run account auth work) (中文(简体) ).

HTTP / 多克语 : 访问 http://localhost:3000/accounts 用于管理浏览器中的账户.

否时 account 参数提供给一个工具,只读工具合并所有账户的结果,同时以适当的权限写入工具自动选择账户.

示例使用

加上你期望的日历集成的正常能力,你也可以做真正的动态多步骤的过程,例如:

1. 跨日历可用性数字 :

   Please provide availability looking at both my personal and work calendar for this upcoming week.
   I am looking for a good time to meet with someone in London for 1 hr.
   

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

   Add this event to my calendar based on the attached screenshot.
   

   支持的图像格式: PNG, JPEG, GIF 图像可以包含日期、时间、位置和描述等事件细节

3. 日历分析:

   What events do I have coming up this week that aren't part of my usual routine?
   

4. 检查出勤情况 :

   Which events tomorrow have attendees who have not accepted the invitation?
   

5. 响应邀请 :

   Accept the team meeting invitation on my calendar for tomorrow at 2pm
   

   缩写为注:

   Decline the Friday meeting with a note that I have a scheduling conflict
   

   对经常性事件的反应:

   Accept just this week's standup, but keep future instances as tentative
   

   Decline all future Monday planning meetings
   

6. 自动坐标事件 :

   Here's some availability that was provided to me by someone. {available times}
   Take a look at the times provided and let me know which ones are open on my calendar.
   

可用工具

文档

• 认证设置 - 详细的谷歌云设置
• 高级使用 - 多账户、分批业务
• 部署指南 - HTTP运输,远程接入
• 嵌入向导 - 用stdio和HTTP模式部署多克
• 建筑 - 技术架构概览
• 发展 - 贡献和测试
• 测试 - 单位和综合测试指南
• 多账户更新 - 多账户支助的现状和路线图

赞助

如果Google日历MCP对你有用 你那么喜欢的话 我会非常感激你 赞助我的开源作品。 。 。 .

- 内特

配置

环境变量:

CLI旗优先于环境变量. 数值不正确(例如非数字) PORT 或未知号码 TRANSPORT)在启动时停止服务器出现出错,解析的配置在启动时被登录为 stderr.

GOOGLE_CALENDAR_API_BASE_URL 用于生成 TLS 本身的 Egress 代理,例如 . http://127.0.0.1:10255/tenant-a/calendar。保留路径前缀,所以请求将转到 <url>/calendar/v3/...。日历访问令牌和请求数据发送到此 URL,未加密 http://,所以只指向您控制的代理人。 Token 刷新和登录流量不变: 刷新仍需要到达 oauth2.googleapis.com 直接或通过 HTTPS_PROXY不管这是准备的 与 HTTPS_PROXY 设置,请在 NO_PROXY 直接到达; 批量请求以两种方式直接到达.

工具过滤

您可以限制哪些工具会使用 AI 助手 --enable-tools 旗帜或 ENABLED_TOOLS 环境变量。 这对于:

• 减少上下文的使用:每个工具都从AI的上下文窗口中消耗符. 限制工具可以帮助保存上下文以进行较长的对话.
• 警卫:限制只读操作或特定功能的能力.
• 简单: 只披露您工作流程实际需要的工具.

通过命令行 :

npx @cocal/google-calendar-mcp start --enable-tools list-events,create-event,get-current-time

Claude 桌面配置中的 Via 环境变量 :

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["@cocal/google-calendar-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/credentials.json",
        "ENABLED_TOOLS": "list-events,create-event,get-current-time,update-event"
      }
    }
  }
}

可用工具名称 : list-calendars, (中文(简体) ), list-events, (中文(简体) ), search-events, (中文(简体) ), get-event, (中文(简体) ), list-colors, (中文(简体) ), create-event, (中文(简体) ), create-events, (中文(简体) ), update-event, (中文(简体) ), delete-event, (中文(简体) ), get-freebusy, (中文(简体) ), get-current-time, (中文(简体) ), respond-to-event, (中文(简体) ), manage-accounts

说明: 这个 manage-accounts 工具总是可以使用,不管过滤,因为它是认证管理所需要的.

当工具过滤激活时,服务器向AI助手提供指令,列出哪些工具被禁用. 这使人工智能能够告知用户其他功能存在,但目前无法使用,而无需消耗这些工具计划的全部象征性费用.

如果列表为空或仅包含逗号,服务器将无法从错误开始 .

如果指定无效的工具名称, 服务器将无法从列出所有可用工具的错误开始 .

警卫

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

解决问题

1. 找不到 OAuth 证书文件 :

   • 对于 npx 用户: 您 必须 使用 GOOGLE_OAUTH_CREDENTIALS
   • 校验文件路径为绝对且可访问

2. 认证错误 :

   • 保证您的全权证书文件包含 桌面应用程序 类型
   • 校验您的用户电子邮件为 测试用户 在谷歌云 OAuth 的同意屏幕中
   • 尝试删除已保存的令牌并重新认证
   • 请检查date=中的日期值 (帮助) 无其它进程封堵端口 3500-3505

3. 构建错误 :

   • 运行 npm install && npm run build 再来一次
   • 检查 Node.js 版本( 使用 LTS)
   • 删除 build/ 目录和运行 npm run build

4. 浏览器认证过程中的“ 出错” 屏幕

   • 手动运行认证命令( 见 重新校正 上文)
   • 使用基于铬的浏览器. 测试应用认证可能对某些非铬浏览器无效.

5. “用户比率限制”出错

   • 通常发生在您的 OAuth 证书缺少项目信息时
   • 保证您 gcp-oauth.keys.json 文件包含 project_id
   • 必要时从 Google Cloud 控制台重新下载证书
   • 文件应该有格式 : {"installed": {"project_id": "your-project-id", ...}}

许可证

麻省理工学院

支助

• GitHub 问题
• 文档