# @cocal/google-calendar-mcp 中文文档 规范地址：https://npmcn.com/package/%40cocal/google-calendar-mcp/ 版本：2\.8\.1 npm 元数据更新时间：2026-10-29T20:52:28.430Z 中文译文更新时间：2026-11-10T05:09:03.466Z 软件包许可：MIT 本文由上游 README 翻译，可能存在偏差，请结合原文核对 API、命令与配置。版权与许可归原作者所有。 原始 npm 页面：https://www.npmjs.com/package/%40cocal/google-calendar-mcp 原文对照：https://npmcn.com/package/%40cocal/google-calendar-mcp/?lang=original 项目主页：https://github.com/nspady/google-calendar-mcp#readme 源码仓库：https://github.com/nspady/google-calendar-mcp ## 关键信息（来自 npm 元数据） - 包体积（解压后）：1.1 MB，12 个文件 - 模块格式：ES Module - TypeScript 类型：未声明 - Node.js 要求：\>=20 - 运行依赖：6 个 - 首次发布：2025-06-04T21:02:20.381Z - 最新版本发布：2026-10-29T20:52:28.055Z - 近 30 天下载量：50161（2026-10-10 至 2026-11-08，npm 官方下载统计） - 已发布版本数：34（近 12 个月 13 个） ## 中文简介 谷歌日历 MCP 对日历管理有广泛支持的服务器 ## 安装 ```sh npm install @cocal/google-calendar-mcp ``` 也可以使用：`pnpm add @cocal/google-calendar-mcp`、`yarn add @cocal/google-calendar-mcp`、`bun add @cocal/google-calendar-mcp` ## README # 谷歌日历 MCP 服务器 一个模型背景协议(MCP)服务器,为克洛德等AI助手提供Google日历集成.

Cocal

我也造过 焦值,我想聊天的日历集成: 克劳德内部的可视日历, 显示你一整天在提议的时间, 加上预订链接, 邀请你从对话中管理。 它被托管,因此在桌面和移动上工作,没有Google Cloud设置.

Cocal visual calendar showing work meetings and a personal gym session together on a timeline Cocal event card showing attendees, timezone context, a description, and no conflicts

具有样本日历数据的 Real Cocal UI. 单击任意一个截图来扩展 .

试试Cocal..

* * * ## 特征 - **多账户支助**:连接多个Google账户(如工作,个人)并同时查询 - **多日历支持**: 在单个请求中列出多个日历中的事件 - **交叉冲突**: 检测日历组合中的重叠事件 - **事件管理**: 创建、更新、删除并搜索日历事件 - **经常性事件**: 经常性活动的高级修改能力 - **免费/ Busy 查询**: 检查日历的可用性 - **智能排程**: 日期和时间的自然语言理解 - **智能导入**: 从图像、 PDF 或网络链接添加日历事件 ## 快速启动 > 不想设立"谷歌云"项目?? [焦值](https://cocal.io/?utm_source=google_calendar_mcp&utm_medium=listing&utm_campaign=release&utm_content=quick_start) 是一个在 Claude 在桌面和移动上工作的主机选项. ### 先决条件 1. 启用日历 API 的 Google Cloud 项目 2. OAuth 2.0 证书( Desktop app 类型) ### 谷歌云设置 1. 转到 [谷歌云控台](https://console.cloud.google.com/) 2. 创建新工程或选择现有工程 . 3. 启用 [谷歌日历 API](https://console.cloud.google.com/apis/library/calendar-json.googleapis.com) 你的项目。 确保在启用 API 之前从上行选择正确的项目 . 4. 创建 OAuth 2. 0 证书 : - 转到证书 - 点击“ 创建证书” > “ OAuth 客户端 ID” - 选择应用程序将访问的数据类型“ 用户数据 ” - 添加您的应用程序名称和联系人信息 - 增加以下范围(可选): - `https://www.googleapis.com/auth/calendar.events` 财务报告和审定财务报表 `https://www.googleapis.com/auth/calendar` - 选择“ Desktop app”为应用程序类型( 重要 !) - 保存 Auth 密钥, 您需要在下一步将其路径添加到 JSON 中 - 添加您的电子邮件地址作为测试用户 [观众屏幕](https://console.cloud.google.com/auth/audience) - 注:测试用户可能需要几分钟时间才能加入. OAuth 同意不会允许您在测试用户推广之前继续 . - 关于测试模式的注释: 当一个app在测试模式中时, 认证符将在1周后过期并需要刷新(见下文再认证部分) . ### 安装 **备选案文1:与npx(建议使用)** 添加到您的 Claude 桌面配置 : **马科斯**数字 : `~/Library/Application Support/Claude/claude_desktop_config.json` **窗口**数字 : `%APPDATA%\Claude\claude_desktop_config.json` ```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:当地安装** ```bash git clone https://github.com/nspady/google-calendar-mcp.git cd google-calendar-mcp npm install npm run build ``` 然后使用本地路径或者通过指定路径添加到 Claude 桌面配置 `GOOGLE_OAUTH_CREDENTIALS` 环境变量. **备选办法3:安装嵌入器** ```bash 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 部署指南](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/docker.md) 用于包括 HTTP 传输模式在内的详细配置选项. ### 第一个运行 1. 启动克洛德桌面 2. **请 Claude 使用 Google 日历 MCP 服务器认证** (例如"授权与谷歌日历"). 在使用任何日历工具之前,需要这一步骤——如果没有这一步骤,请求将失败 `-32600` 错误. 3. 完成浏览器中的 OAuth 流量 4. 你准备好使用日历特性了! **用克洛德密码?** 同样的步骤适用——只是要求克洛德在使用任何日历工具之前,先从您的 CLI 会话中认证Google Calendar MCP 服务器. ### 重新校正 如果您处于测试模式( 默认) , 标志在7天后过期 。 如果您正在使用 Claude Desktop 这样的客户端, 它应该打开浏览器窗口来自动重新启用 。 然而,如果看到认证错误,您也可以通过遵循这些步骤来解决: **Npx 用户:** ```bash export GOOGLE_OAUTH_CREDENTIALS="/path/to/your/gcp-oauth.keys.json" npx @cocal/google-calendar-mcp auth ``` **当地安装:** ```bash npm run auth ``` **避免每周重新校正**,将您的应用程序发布到生产模式(无需验证) : 1. 上Google Cloud Console "APIS & Services" "OAuth同意屏幕" 2. 点击“ PUBLISH AP” 确认 3. 7天后你的标志就不再过期了 但Google会发出警告说 应用程序没有得到验证. 见 [认证指南](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/authentication.md#avoiding-token-expiration) 详细情况. ## 服务账户认证( 可选) 服务账户带有自己的长寿密钥, 因此没有浏览器同意步骤 并且没有新鲜的纪念品过期。 这是发布 OAuth 应用程序的替代方案 当上面的每周重新校正是不切实际的——无头服务器,容器, CI,或者一个应用程序,你宁愿离开 在测试状态. ### 此日历用于 | 日历 | 工作吗? | 如何允许进入 | | --- | --- | --- | | 个人 `@gmail.com` 日历 | **对** | 与服务账户的电子邮件地址共享日历 | | 谷歌工作空间日历 | **对** | 共享, 或者使用全域权限来假扮用户 | | 别人给你的日历 | 没有 | 所有者必须直接与服务账户分享 | 共享是授权访问的内容——服务账户是一个独立的身份,并看到 没有默认的. **无需全域授权** 个人日历 大小写; 只有在您想要服务账户行事时才需要 _作为_ 用户. ### 限制 - **无法邀请参与者 .** API拒绝这一点 _"服务账户不能 请无域-广域授权代表团出席者”_其他一切 - 创建、更新、删除、搜索、自由/忙碌——正常工作. - **`calendarId` 必须明确.** `primary` 指服务账户自己的, 空日历;通过日历地址(如. `you@gmail.com`相反. - **`list-calendars` 返回无.** 与服务账户共享的日历不 显示于 `calendarList` 除非明确添加。 由 id 编辑的地址日历 . ### 设置 1. 在您的 Google Cloud 项目中创建服务账户和 JSON 密钥 : ```bash 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. 将服务器指向密钥 : ```json { "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 助手中直接添加、 列出或删除账户的工具 - 不需要终端。 见 [认证指南](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/authentication.md#managing-multiple-accounts) 详细情况. **CLI: 爱丽丝** 对于初始设置, 使用 `npm run account auth ` (例如, `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. ``` ## 可用工具 | 工具 | 说明 | | --- | --- | | `list-calendars` | 列出所有可用的日历 | | `list-events` | 列出带有日期过滤器的事件 | | `get-event` | 使用 ID 获取特定事件的细节 | | `search-events` | 通过文本查询搜索事件 | | `create-event` | 创建新日历事件, 可选择带有事件标签的颜色( N)`eventLabelId`(中文(简体) ) | | `create-events` | 在一个共享默认的呼叫中创建多个事件( skips 冲突检测) | | `update-event` | 更新已有的事件, 包括设置或删除事件标签 | | `delete-event` | 删除事件 | | `respond-to-event` | 响应事件邀请( 接受、 下降、 可能、 无回应) | | `get-freebusy` | 检查各日历的可用性,包括外部日历 | | `get-current-time` | 在日历的时区中获取当前日期和时间 | | `list-colors` | 列出遗留事件颜色, 附加日历事件标签( 定制颜色) `calendarId` | | `manage-accounts` | 添加、 列表或删除连接的 Google 账户 | ## 文档 - [认证设置](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/authentication.md) - 详细的谷歌云设置 - [高级使用](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/advanced-usage.md) - 多账户、分批业务 - [部署指南](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/deployment.md) - HTTP运输,远程接入 - [嵌入向导](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/docker.md) - 用stdio和HTTP模式部署多克 - [建筑](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/architecture.md) - 技术架构概览 - [发展](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/development.md) - 贡献和测试 - [测试](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/testing.md) - 单位和综合测试指南 - [多账户更新](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/multi-account-updates.md) - 多账户支助的现状和路线图 ## 赞助 如果Google日历MCP对你有用 你那么喜欢的话 我会非常感激你 [赞助我的开源作品](https://github.com/sponsors/nspady)。 。 。 . \- 内特 ## 配置 **环境变量:** CLI旗优先于环境变量. 数值不正确(例如非数字) `PORT` 或未知号码 `TRANSPORT`)在启动时停止服务器出现出错,解析的配置在启动时被登录为 stderr. | 变量 | CLI 旗帜 | 默认 | 说明 | | --- | --- | --- | --- | | `GOOGLE_OAUTH_CREDENTIALS` | | `gcp-oauth.keys.json` 在软件包根中 | OAuth 证书文件的路径 | | `GOOGLE_OAUTH_REDIRECT_BASE` | | 取消设置( 回转) `http://localhost:`(中文(简体) ) | OAuth 通过隧道或反向代理认证时的公用基址调回( 见 [文件/核证](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/authentication.md#remote--headless-authentication-google_oauth_redirect_base)(中文(简体) ) | | `GOOGLE_SERVICE_ACCOUNT_KEY` | | 未设定 | 明确服务账户密钥文件的路径 | | `GOOGLE_APPLICATION_CREDENTIALS` | | 未设定 | Ambient Google 证书文件, 当服务器没有 OAuth 证书文件时使用 | | `GOOGLE_SERVICE_ACCOUNT_SUBJECT` | | 未设定 | 假冒全域权限的工作空间用户 | | `GOOGLE_CALENDAR_MCP_TOKEN_PATH` | | `$XDG_CONFIG_HOME/google-calendar-mcp/tokens.json` | 自定义令牌存储位置 | | `XDG_CONFIG_HOME` | | `~/.config` | 用于符号存储的基础配置目录( 如果设置了 GOGLE CALENDAR MCP TOKEN PATH , 则已启用) | | `GOOGLE_ACCOUNT_MODE` | | `normal` | 用于单账户操作的账户昵称和 `auth` 命令 | | `ENABLED_TOOLS` | `--enable-tools` | 所有工具 | 以逗号分隔的要曝光的工具列表(参见工具过滤) | | `TRANSPORT` | `--transport` | `stdio` | 运输类型 : `stdio` 或者说 `http` | | `PORT` | `--port` | `3000` | HTTP运输港(1-65535) | | `HOST` | `--host` | `127.0.0.1` | HTTP 运输绑定地址 | | `DEBUG` | `--debug` | `false` | 保留: `true` 在启动日志中被接受并显示,但目前无法额外日志 | | `GOOGLE_CALENDAR_API_BASE_URL` | | `https://www.googleapis.com` | 将日历 API 调用发送到此基址( 见下文) | | `NODE_ENV` | | 未设定 | `test` 跳过启动认证并使用 `test` 账户命名空间(用于测试套件) | `GOOGLE_CALENDAR_API_BASE_URL` 用于生成 TLS 本身的 Egress 代理,例如 . `http://127.0.0.1:10255/tenant-a/calendar`。保留路径前缀,所以请求将转到 `/calendar/v3/...`。日历访问令牌和请求数据发送到此 URL,未加密 `http://`,所以只指向您控制的代理人。 Token 刷新和登录流量不变: 刷新仍需要到达 `oauth2.googleapis.com` 直接或通过 `HTTPS_PROXY`不管这是准备的 与 `HTTPS_PROXY` 设置,请在 `NO_PROXY` 直接到达; 批量请求以两种方式直接到达. ### 工具过滤 您可以限制哪些工具会使用 AI 助手 `--enable-tools` 旗帜或 `ENABLED_TOOLS` 环境变量。 这对于: - **减少上下文的使用**:每个工具都从AI的上下文窗口中消耗符. 限制工具可以帮助保存上下文以进行较长的对话. - **警卫**:限制只读操作或特定功能的能力. - **简单**: 只披露您工作流程实际需要的工具. **通过命令行 :** ```bash npx @cocal/google-calendar-mcp start --enable-tools list-events,create-event,get-current-time ``` **Claude 桌面配置中的 Via 环境变量 :** ```json { "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. **浏览器认证过程中的“ 出错” 屏幕** - 手动运行认证命令( 见 [重新校正](https://npmcn.com/package/%40cocal/google-calendar-mcp/#readme-re-authentication) 上文) - 使用基于铬的浏览器. 测试应用认证可能对某些非铬浏览器无效. 5. **“用户比率限制”出错** - 通常发生在您的 OAuth 证书缺少项目信息时 - 保证您 `gcp-oauth.keys.json` 文件包含 `project_id` - 必要时从 Google Cloud 控制台重新下载证书 - 文件应该有格式 : `{"installed": {"project_id": "your-project-id", ...}}` ## 许可证 麻省理工学院 ## 支助 - [GitHub 问题](https://github.com/nspady/google-calendar-mcp/issues) - [文档](https://npmcn.com/package/%40cocal/google-calendar-mcp/docs/) ## 常见问题 ### @cocal/google-calendar-mcp 是什么？ 谷歌日历 MCP 对日历管理有广泛支持的服务器 ### 如何安装 @cocal/google-calendar-mcp？ 在项目目录运行 npm install @cocal/google-calendar-mcp，或使用 pnpm add / yarn add / bun add。它还提供命令行工具 google-calendar-mcp，可以用 npx google-calendar-mcp 直接运行。 ### @cocal/google-calendar-mcp 支持 TypeScript 吗？ 该包的 package\.json 没有声明类型入口。需要类型提示时，可以在 npm 上查找社区维护的 @types/cocal\_\_google-calendar-mcp 是否存在。 ### @cocal/google-calendar-mcp 支持 ESM 还是 CommonJS？ 以 ES Module 形式发布，推荐使用 import 引入。在 CommonJS 项目中，Node\.js 20\.19\+ / 22\.12\+ 可以直接 require\(\) 不含顶层 await 的 ES Module，更早的版本需要改用动态 import\(\)。 ### @cocal/google-calendar-mcp 需要什么版本的 Node\.js？ package\.json 的 engines 字段要求 Node\.js \>=20。版本不符时 npm 默认只给出警告，开启 engine-strict 后会拒绝安装。 ### @cocal/google-calendar-mcp 可以商用吗？ @cocal/google-calendar-mcp 使用 MIT 许可。宽松许可：允许商业使用、修改和再分发，通常只需在分发时保留原版权与许可声明。以上为概括，不构成法律意见，请以许可原文为准。 ### @cocal/google-calendar-mcp 的下载量有多少？ 根据 npm 官方下载统计，@cocal/google-calendar-mcp 在 2026/10/10 – 2026/11/08 这 30 天内被下载 50,161 次，日均约 1,672 次。下载量会把 CI 构建、镜像同步和作为其他包依赖的安装一并计入，适合横向比较热度，不能直接等同于使用人数。 ### @cocal/google-calendar-mcp 还在维护吗？ 最新版本 2\.8\.1 发布于 2026/10/30（11 天前）；至今共发布 34 个版本，其中过去 12 个月发布了 13 个；首次发布于 2025/06/05。发布频率只是参考信号：功能稳定的工具可能很少需要更新，建议结合源码仓库的 issue 和提交记录判断。