日历集成服务

谷歌日历MCP服务器

一个模型上下文协议（MCP）服务器，为克劳德等人工智能助手提供谷歌日历集成。

特性

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

快速开始

先决条件

1. 启用日历API的谷歌云项目
2. OAuth 2.0凭据（桌面应用程序类型）

谷歌云设置

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

安装

选项1：与npx一起使用（推荐）

添加到您的Claude Desktop配置中：

macOS: ~/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 Desktop配置中 GOOGLE_OAUTH_CREDENTIALS 环境变量。

选项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. 启动克劳德桌面
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. 转到谷歌云控制台→ “API和服务”→ “OAuth同意屏幕”
2. 点击“发布APP”并确认
3. 您的令牌将在7天后不再过期，但谷歌将在连接到应用程序时显示一个更具威胁性的警告，告知其未经验证。

看 身份验证指南 了解详情。

示例用法

除了日历集成的正常功能外，您还可以执行真正动态的多步骤流程，例如：

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. 自动协调事件：

   复制

   Here's some available 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.
   

可用工具

文档

• 身份验证设置 -详细的Google Cloud设置
• 高级用法 -多账户、批量操作
• 部署指导 -HTTP传输，远程访问
• Docker指南 -使用stdio和HTTP模式部署Docker
• OAuth验证 -从测试模式转移到生产模式
• 建筑 -技术架构概述
• 发展 -贡献和测试
• 测试 -单元和集成测试指南

配置

环境变量：

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

Claude桌面配置位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %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浏览器可能不支持测试应用身份验证。

手动认证

对于重新身份验证或故障排除：

# For npx installations
export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/credentials.json"
npx @cocal/google-calendar-mcp auth

# For local installations
npm run auth

许可证

麻省理工学院

支持

• GitHub问题
• 文档