⚙

日历集成服务

为AI助手提供Google日历集成的模型上下文协议（MCP）服务器，支持多账户、多日历管理和智能事件处理。

作者 By nspady
本地部署 AI助手集成 多账户管理
GitHub

谷歌日历MCP服务器

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

特性

  • 多账户支持：连接多个谷歌帐户（例如，工作、个人）并同时查询它们
  • 多日历支持：在单个请求中列出多个日历中的事件
  • 跨账户冲突：检测日历任意组合中的重叠事件
  • 活动管理：创建、更新、删除和搜索日历事件
  • 重复事件：重复事件的高级修改功能
  • 忙/闲查询：检查日历上的可用性
  • 智能调度：日期和时间的自然语言理解
  • 智能导入：从图像、PDF或web链接添加日历事件

快速开始

先决条件

  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

JSON``` 1 2 3 4 5 6 7 8 9 10 11{ “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：本地安装**


BASH```
1
2
3
4git 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安装

BASH``` 1 2 3 4git 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. 您已准备好使用日历功能！


**使用克劳德代码？** 同样的步骤也适用——在使用任何日历工具之前，只需让Claude在CLI会话中通过Google Calendar MCP服务器进行身份验证。


### 重新认证


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


**对于npx用户：**


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

对于本地安装：

BASH``` 1npm run auth


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


1. 转到谷歌云控制台→ “API和服务”→ “OAuth同意屏幕”
2. 点击“发布APP”并确认
3. 您的代币将在7天后不再过期，但谷歌将显示一条关于该应用程序未经验证的警告。


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


## 管理多个帐户


连接多个Google帐户并同时使用它们。


**聊天中（推荐）：** 使用 `manage-accounts` 该工具可直接从您的AI助手中添加、列出或删除帐户，无需终端。请参阅 身份验证指南 了解详情。


**CLI：** 对于初始设置，请使用 `npm run account auth <nickname>` （例如。， `npm run account auth work`).


**HTTP/Docker：** 访问 `http://localhost:3000/accounts` 在浏览器中管理帐户。


当否 `account` 参数提供给工具，只读工具合并所有帐户的结果，而写入工具自动选择具有适当权限的帐户。


## 示例用法


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


1. **跨日历可用性**:

1 2Please 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. 添加来自屏幕截图、图像和其他数据源的事件：

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


支持的图像格式：PNG、JPEG、GIF
图像可以包含事件详细信息，如日期、时间、位置和描述
3. 日历分析：

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

4. 检查出勤情况：

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

5. 回复邀请：

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


用便条拒绝：

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


对重复发生的事件做出响应：

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

1Decline all future Monday planning meetings

6. 自动协调事件：

1 2Here’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.



## 可用工具


| 工具 | 说明 |
| --- | --- |
| `list-calendars` | 列出所有可用日历 |
| `list-events` | 使用日期筛选列出事件 |
| `get-event` | 按ID获取特定事件的详细信息 |
| `search-events` | 按文本查询搜索事件 |
| `create-event` | 创建新的日历事件 |
| `update-event` | 更新现有事件 |
| `delete-event` | 删除事件 |
| `respond-to-event` | 响应活动邀请（接受、拒绝、也许、无响应） |
| `get-freebusy` | 检查日历（包括外部日历）的可用性 |
| `get-current-time` | 获取日历时区中的当前日期和时间 |
| `list-colors` | 列出可用的事件颜色 |
| `manage-accounts` | 添加、列出或删除已连接的Google帐户 |


## 文档


- 身份验证设置 -详细的Google Cloud设置
- 高级用法 -多账户、批量操作
- 部署指导 -HTTP传输，远程访问
- Docker指南 -使用stdio和HTTP模式部署Docker
- 建筑 -技术架构概述
- 发展 -贡献和测试
- 测试 -单元和集成测试指南
- 多帐户更新 -多账户支持的现状和路线图


## 赞助


如果谷歌日历MCP对你有用，你也这么想，如果你能考虑，我将不胜感激 [赞助我的开源工作](https://github.com/sponsors/nspady).


谢谢！-内特


## 配置


**环境变量：**


- `GOOGLE_OAUTH_CREDENTIALS` -OAuth凭据文件的路径
- `GOOGLE_CALENDAR_MCP_TOKEN_PATH` -自定义令牌存储位置（可选）
- `ENABLED_TOOLS` -以逗号分隔的要启用的工具列表（请参阅下面的工具筛选）


### 工具筛选


您可以使用 `--enable-tools` 旗帜或 `ENABLED_TOOLS` 环境变量。这有助于：


- **减少上下文使用**：每个工具都会从AI的上下文窗口中消耗令牌。限制工具可以帮助为更长的对话保留上下文。
- **安全**：将功能限制为只读操作或特定功能。
- **简洁**：只公开工作流程实际需要的工具。


**通过命令行：**


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

通过Claude Desktop配置中的环境变量：

JSON``` 1 2 3 4 5 6 7 8 9 10 11 12{ “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`, `update-event`, `delete-event`, `get-freebusy`, `get-current-time`, `respond-to-event`, `manage-accounts`


**注：** 这 `manage-accounts` 无论过滤如何，该工具始终可用，因为它是身份验证管理所必需的。


当工具过滤处于活动状态时，服务器会向AI助手提供指令，列出哪些工具被禁用。这允许AI通知用户存在其他功能，但目前不可用，而无需消耗这些工具模式的全部令牌成本。


如果列表为空或仅包含逗号，服务器将无法启动并出现错误。


如果指定了无效的工具名称，服务器将无法启动，并显示列出所有可用工具的错误。


## 安全


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


### 故障排除


1. **找不到OAuth凭据文件：**


- 对于npx用户：您 **必须** 使用指定凭据文件路径 `GOOGLE_OAUTH_CREDENTIALS`
- 验证文件路径是否绝对且可访问
2. **身份验证错误：**


- 确保您的凭据文件包含 **桌面应用** 类型
- 验证您的用户电子邮件是否已添加为 **测试用户** 在Google Cloud OAuth同意屏幕中
- 尝试删除已保存的令牌并重新进行身份验证
- 检查是否没有其他进程阻塞端口3500-3505
3. **构建错误：**


- 跑 `npm install && npm run build` 再次
- 检查Node.js版本（使用LTS）
- 删除 `build/` 目录并运行 `npm run build`
4. **浏览器身份验证期间出现“出错”屏幕**


- 手动运行auth命令（请参阅 重新认证 以上）
- 使用基于Chromium的浏览器。测试应用程序身份验证可能无法在某些非Chromium浏览器上运行。
5. **“超出用户速率限制”错误**


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


## 许可证


麻省理工学院


## 支持


- [GitHub问题](https://github.com/nspady/google-calendar-mcp/issues)
- 文档