AI导哈

Google日历MCP服务器

基于Node/TypeScript的MCP服务器，通过MCP工具提供Google日历的读写功能，并带有本地变更日志以跟踪创建/更新/删除的事件。

  • by BasedCodeDev
  • TypeScript
  • 本地部署
  • 更新于
在 GitHub 查看 Fehrox/GoogleCalendarMCP

使用说明

基于。GCMCP——谷歌日历MCP服务器

Node/TypeScript MCP服务器，通过MCP工具公开Google日历读/写，并具有本地更改日志来跟踪创建/更新/删除的事件。

前提条件

  • 节点18+（与节点20/25一起测试）
  • npm
  • 谷歌OAuth客户端（推荐OAuth“桌面应用程序”）

安装

cd /home/seb/Work/Based.GCMCP
npm install

配置环境

创建 .env 在项目根目录中（请参见 .env.example):

GOOGLE_CLIENT_ID=...
GOOGLE_CLIENT_SECRET=...
GOOGLE_REFRESH_TOKEN=...   # fill after bootstrap
GOOGLE_CALENDAR_IDS=       # optional comma-separated list, otherwise primary
DEFAULT_TIMEZONE=Australia/Brisbane
EVENTS_NEXT_DAYS=14
MAX_RESULTS_DEFAULT=50

获取刷新令牌

npm run token:bootstrap
  1. 打开打印的URL，批准访问。
  2. 重定向到 http://localhost:53682/oauth2callback 可能会显示连接错误；复制 code=... URL栏中的值。
  3. 将代码粘贴回终端。
  4. 脚本打印刷新令牌（并写入 .env 如果可以的话）。如果 .env 已存在，请粘贴 GOOGLE_REFRESH_TOKEN=... 手动。

替代方案：使用带有您的客户端ID/密钥、日历范围的Google OAuth Playground，并将刷新令牌复制到 .env.

运行服务器

npm start

此构建（tsc）然后通过stdio运行MCP服务器。MCP使用stdout发送协议消息，因此 .npmrc 套 loglevel=silent 阻止npm横幅污染流；保留stderr上的所有日志记录。

配置您的MCP客户端以启动：

  • 命令： npm
  • args： ["start"]
  • cwd： /home/seb/Work/Based.GCMCP

使用添加 codex mcp add

在Codex CLI中全局注册服务器：

codex mcp add /bin/bash -- -lc 'cd /home/seb/Work/Based.GCMCP && npm start' google-calendar-mcp

如果在其他地方克隆，请调整cwd；这 google-calendar-mcp 名称是任意的。确保您的 .env 在添加之前填充。如果你想完全避免使用npm，只需构建一次(npm run build)并指向Codex node /home/seb/Work/Based.GCMCP/dist/src/index.js.

工具（标准MCP）

  • health-status：检查身份验证并列出可访问的日历。
  • events-list：按时间窗口列出事件；支持 timeMin, timeMax, calendarIds?, query?, maxResults?, pageToken?, timeZone?.
  • events-next：未来N天即将发生的事件(days?，默认值14）。
  • events-create：创建事件； dryRun 默认为true。集 dryRun:false 写。
  • events-update：更新事件（如果提供，则遵守etag）； dryRun 默认为true。
  • events-delete：删除事件（如果提供，则尊重etag）； dryRun 默认为true。
  • events-changes：查询本地更改日志。

资源

  • calendar://list：日历元数据列表。
  • calendar://{calendarId}：特定日历的元数据。

更改跟踪

突变附加到 data/event-log.json 包含操作、日历ID、事件ID、etag和时间戳。通过查询 events-changes （按操作/calendarId、限制过滤）。

干运行默认值

所有变异工具默认为 dryRun: true；set dryRun: false 实际写入/更新/删除。

测试

npm test

构建并运行node:测试套件 dist/tests.

备注

  • 时区优先级：请求参数>日历TZ> DEFAULT_TIMEZONE.
  • 不支持多个日历的分页（谷歌每个日历返回nextPageToken）；分页时使用单个日历。
  • 429/5xx支持退回/回退；每个请求的超时时间为10秒。

相关 MCP