Google Calendar

google-cal-mcp

用于 Google Calendar 的 MCP 服务——可列出、创建、更新和管理日历事件。

使用场景

安排会议：“下周安排一次与 Sarah 的 30 分钟同步会议” → 查找空闲时段，创建带 Meet 链接的事件，并发送邀请。

回复邀请：“接受团队外出活动的邀请，但拒绝供应商演示的邀请” → 自动回复待处理的邀请。

查找可用时间：“我本周四下午什么时候有空？” → 查询你的日历并返回空闲时段。

重新安排事件：“把我和 Alex 的 1:1 会议改到周五下午 2 点” → 更新事件并通知参会者。

每日简报：“我今天的日历上有什么安排？” → 列出所有事件及其时间、地点和参会者。

预留专注时间：“明天上午预留 2 小时做深度工作” → 创建日历事件，为你留出时间。

（这些只是示例——任何需要访问日历的工作流都可以使用此服务。）

设置

1. 创建 Google OAuth 凭据

1. 前往 Google Cloud Console
2. 创建新项目（或使用现有项目）
3. 启用 Google Calendar API
4. 前往 APIs & Services → OAuth consent screen，设置同意屏幕
5. 前往 APIs & Services → Credentials → Create Credentials → OAuth client ID
6. 选择 Web application
7. 将 http://localhost:3000/callback 添加到 Authorized redirect URIs
8. 记下你的 Client ID 和 Client Secret

2. 运行服务

GOOGLE_CLIENT_ID='your-client-id' \
GOOGLE_CLIENT_SECRET='your-client-secret' \
MCP_TRANSPORT=http \
npm start

服务默认运行在 http://localhost:3000。使用 PORT=3001 更改端口。

3. 添加到你的 MCP 客户端

服务运行后，请按照 install-mcp 上的说明操作。该页面会为你的 MCP 客户端（Claude Code、Claude Desktop、Cursor、Cline、VS Code 等）生成正确的配置。

架构

此服务作为 Google 的 OAuth 代理：

graph LR
    A[MCP client] <--> B[google-cal-mcp] <--> C[Google OAuth/API]

1. 服务通过 /.well-known/oauth-authorization-server 声明自己是 OAuth 授权服务器
2. /register 返回 Google OAuth 客户端凭据
3. /authorize 重定向到 Google，并将客户端的回调 URL 编码到 state 中
4. /callback 接收来自 Google 的授权码，并转发到客户端的回调地址
5. /token 将令牌请求代理到 Google，并注入客户端凭据
6. /mcp 处理 MCP 请求，并使用 bearer token 调用 Calendar API

服务不保存任何令牌或状态——它只代理 Google 的 OAuth 请求。

工具

工具	描述
日历
calendars_list	列出用户有权访问的所有日历
calendarlist_insert	订阅共享日历
calendarlist_update	更新日历设置（颜色、可见性、提醒）
calendarlist_delete	取消订阅日历
事件
events_list	列出指定时间范围内的事件，并支持搜索和筛选
event_get	获取特定事件的详细信息
event_create	创建包含参会者和 Meet 链接的新事件
event_update	更新现有事件
event_delete	删除事件
event_respond	回复邀请（接受／拒绝／暂定）
event_move	将事件移至其他日历
event_instances	获取重复事件的各个实例
可用时间
freebusy_query	查找空闲／忙碌时段以安排日程
共享
acl_list	列出有权访问日历的用户
颜色
colors_get	获取日历／事件可用的调色板

Calendar API 权限范围

• calendar - 完全访问日历
• calendar.events - 读取／写入事件

贡献

欢迎在 GitHub 上提交拉取请求！开始参与：

1. 安装 Git 和 Node.js
2. 克隆仓库
3. 使用 npm install 安装依赖
4. 运行 npm run test 执行测试
5. 使用 npm run build 构建

发布

版本遵循语义化版本规范。

发布步骤：

1. 使用 npm version <major | minor | patch> 更新版本号
2. 运行 git push --follow-tags 推送并附带标签
3. 等待 GitHub Actions 发布到 NPM 注册表。