google-calendar

Google Calendar Workspace MCP 服务

这是一个使用服务账号身份验证和全域委派功能集成 Google Calendar 的 MCP（Model Context Protocol）服务。此服务可让 AI 助手与 Google Calendar 交互，以列出活动、创建活动、管理日历并查询可用时间。

功能

• 列出活动：查看指定时间范围内的日历活动，并可筛选
• 获取活动详情：检索特定活动的完整信息
• 创建活动：创建包含参与者、地点和说明的新日历活动
• 更新活动：修改现有活动（PATCH 语义——仅更新提供的字段）
• 删除活动：移除活动，并可选择是否通知参与者
• 列出日历：发现可用日历
• 查询空闲/忙碌时间：检查可用时间并查找忙碌时段

前置条件

1. Google Cloud 项目，并已启用 Calendar API
2. 服务账号，并启用全域委派
3. Google Workspace 管理员访问权限，用于授予日历权限

设置

1. 创建 Google Cloud 服务账号

1. 前往 Google Cloud Console
2. 创建或选择一个项目
3. 启用 Google Calendar API：
   • 前往“APIs & Services” > “Library”
   • 搜索“Google Calendar API”
   • 点击“Enable”
4. 创建服务账号：
   • 前往“IAM & Admin” > “Service Accounts”
   • 点击“Create Service Account”
   • 输入名称和说明
   • 点击“Create and Continue”
   • 跳过授予角色（全域委派不需要）
   • 点击“Done”
5. 为服务账号创建密钥：
   • 点击创建的服务账号
   • 前往“Keys”标签页
   • 点击“Add Key” > “Create new key”
   • 选择“JSON”格式
   • 下载密钥文件
6. 记下服务账号的 Client ID（可在服务账号详情中找到）

2. 启用全域委派

1. 在服务账号详情中，点击“Show domain-wide delegation”
2. 勾选“Enable Google Workspace Domain-wide Delegation”
3. 保存更改
4. 记下 Client ID（下一步需要用到）

3. 在 Google Workspace 管理员控制台中授予日历权限

1. 前往 Google Workspace Admin Console
2. 前往“Security” > “Access and data control” > “API Controls”
3. 点击“Manage Domain Wide Delegation”
4. 点击“Add new”
5. 输入服务账号的 Client ID
6. 在“OAuth Scopes”字段中添加：

   https://www.googleapis.com/auth/calendar
   

7. 点击“Authorize”

4. 配置环境变量

从下载的 JSON 密钥文件中提取以下内容：

• client_email：服务账号邮箱
• private_key：私钥（包含 -----BEGIN PRIVATE KEY----- 和 -----END PRIVATE KEY-----）

设置以下环境变量：

export GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL="[email protected]"
export GCAL_SERVICE_ACCOUNT_PRIVATE_KEY="-----BEGIN PRIVATE KEY-----\nYour private key content\n-----END PRIVATE KEY-----"
export GCAL_IMPERSONATE_EMAIL="[email protected]"

注意：GCAL_IMPERSONATE_EMAIL 应为你要访问其日历的用户邮箱地址。

安装

使用 NPX（推荐）

npx google-calendar-workspace-mcp-server

使用 NPM

npm install -g google-calendar-workspace-mcp-server
google-calendar-workspace-mcp-server

在 Claude Desktop 中使用

将此配置添加到 Claude Desktop 配置文件中：

macOS：~/Library/Application Support/Claude/claude_desktop_config.json Windows：%APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["google-calendar-workspace-mcp-server"],
      "env": {
        "GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL": "[email protected]",
        "GCAL_SERVICE_ACCOUNT_PRIVATE_KEY": "-----BEGIN PRIVATE KEY-----\nYour private key\n-----END PRIVATE KEY-----",
        "GCAL_IMPERSONATE_EMAIL": "[email protected]"
      }
    }
  }
}

工具组

默认情况下，所有工具均已启用（读写权限）。设置 ENABLED_TOOLGROUPS 环境变量可将服务限制为只读操作：

{
  "mcpServers": {
    "google-calendar": {
      "command": "npx",
      "args": ["google-calendar-workspace-mcp-server"],
      "env": {
        "GCAL_SERVICE_ACCOUNT_CLIENT_EMAIL": "...",
        "GCAL_SERVICE_ACCOUNT_PRIVATE_KEY": "...",
        "GCAL_IMPERSONATE_EMAIL": "...",
        "ENABLED_TOOLGROUPS": "readonly"
      }
    }
  }
}

可用工具组：

组	包含的工具
readwrite	全部 7 个工具（读写）——默认包含
readonly	只读工具：list_calendar_events、get_calendar_event、list_calendars、query_calendar_freebusy

仅使用 readonly 时，写入工具（create_calendar_event、update_calendar_event、delete_calendar_event）不可用。

可用工具

list_calendar_events

列出日历在可选时间范围内的事件。

参数：

• calendar_id（可选）：日历 ID（默认值："primary"）
• time_min（可选）：RFC3339 格式的开始时间
• time_max（可选）：RFC3339 格式的结束时间
• max_results（可选）：要返回的最大事件数（默认值：10，最大值：250）
• query（可选）：自由文本搜索查询
• single_events（可选）：展开重复事件（默认值：true）
• order_by（可选）："startTime" 或 "updated"

示例：

List my events for the next week

get_calendar_event

获取特定事件的详细信息。

参数：

• event_id（必填）：事件 ID
• calendar_id（可选）：日历 ID（默认值："primary"）

示例：

Get details for event ID abc123

create_calendar_event

创建新的日历事件。

参数：

• summary（必填）：事件标题
• start_datetime 或 start_date（必填）：事件开始时间
• end_datetime 或 end_date（必填）：事件结束时间
• description（可选）：事件描述
• location（可选）：事件地点
• attendees（可选）：电子邮件地址数组
• calendar_id（可选）：日历 ID（默认值："primary"）

示例：

Create a meeting tomorrow at 2pm for 1 hour titled "Team Sync"

update_calendar_event

更新现有日历事件。采用 PATCH 语义——仅更新你提供的字段，其他字段保持不变。

参数：

• event_id（必填）：要更新的事件 ID
• calendar_id（可选）：日历 ID（默认值："primary"）
• summary（可选）：新的事件标题
• description（可选）：新的事件描述
• location（可选）：新的事件地点
• start_datetime 或 start_date（可选）：新的开始时间
• end_datetime 或 end_date（可选）：新的结束时间
• attendees（可选）：更新后的参会者电子邮件地址数组
• send_updates（可选）："all"、"externalOnly" 或 "none"——是否发送更新通知

示例：

Update event abc123 to change the title to "Team Standup"

delete_calendar_event

删除日历事件。

参数：

• event_id（必填）：要删除的事件 ID
• calendar_id（可选）：日历 ID（默认值："primary"）
• send_updates（可选）："all"、"externalOnly" 或 "none"——是否发送取消通知

示例：

Delete event abc123

list_calendars

列出已通过身份验证的用户可用的所有日历。

参数：

• max_results（可选）：要返回的最大日历数（默认值：50，最大值：250）

示例：

Show all my calendars

query_calendar_freebusy

查询日历的空闲/忙碌信息。

参数：

• time_min（必填）：RFC3339 格式的开始时间
• time_max（必填）：RFC3339 格式的结束时间
• calendar_ids（必填）：要检查的日历 ID 数组
• timezone（可选）：查询所用的时区

示例：

Check if I'm free tomorrow between 2pm and 4pm

开发

# Install dependencies
npm run install-all

# Build the project
npm run build

# Run in development mode
npm run dev

# Run tests
npm test

# Run integration tests
npm run test:integration

# Run all tests
npm run test:all

安全注意事项

• 私钥安全：切勿将服务账号私钥提交到版本控制中
• 最小权限：仅授予所需的最少 OAuth 范围
• 密钥轮换：定期轮换服务账号密钥
• 访问日志：在 Google Cloud Console 中监控服务账号的使用情况

故障排除

身份验证失败

• 确认服务账号凭据正确
• 确保已启用全域委派
• 检查 Admin Console 中是否已授权正确的 OAuth 范围
• 确认模拟的电子邮件地址正确

权限被拒绝

• 确保已在 Google Workspace Admin Console 中授予日历范围（https://www.googleapis.com/auth/calendar）
• 确认被模拟的用户有权访问该日历

找不到日历

• 检查日历 ID 是否正确
• 确认被模拟的用户有权访问该日历
• 使用 list_calendars 查找可用的日历 ID

许可证

MIT

贡献

请参阅 CONTRIBUTING.md 了解相关指南。