Google日历任务管理服务

谷歌日历任务mcp

用于谷歌日历、谷歌任务和Gmail的MCP服务器，带有安全护栏。

专为配合使用而设计 克劳德代码 以及任何MCP兼容客户端。

特性

• 21工具：日历事件、任务和Gmail邮件的完整CRUD
• 安全护栏：每日写入限制、受保护的日历/任务列表、过去事件保护、定期系列保护、Gmail发送批准
• 可选审计日志记录：每月跟踪所有写入操作的JSON文件
• 跨平台：Windows、macOS、Linux
• 可配置的 通过环境变量和 guardrails.json
• 测试模式 用于在没有Google API证书的情况下进行开发

先决条件

• Node.js 18+
• 启用了日历、任务和Gmail API的Google Cloud项目
• OAuth 2.0客户端ID（类型：桌面）

快速开始

# 1. Clone and install
git clone https://github.com/talh/google-calendar-tasks-mcp.git
cd google-calendar-tasks-mcp
npm install

# 2. Build
npm run build

# 3. Authenticate (one-time)
node auth.js

# 4. Test with MCP Inspector
npm run inspect

谷歌云项目设置

1. 首选 console.cloud.google.com
2. 创建新项目（或选择现有项目）
3. 启用 谷歌日历API:
   • 导航到API和服务>库
   • 搜索“Google日历API”并启用它
4. 启用 谷歌任务API:
   • 搜索“Google任务API”并启用它
5. 启用 Gmail API:
   • 搜索“Gmail API”并启用它
6. 配置 OAuth 授权界面:
   • 导航到API和服务>OAuth同意屏幕
   • 选择“外部”用户类型
   • 填写必填字段（应用程序名称、支持电子邮件）
   • 添加作用域： calendar.events, tasks，以及 gmail.modify
   • 将自己添加为测试用户
7. 创建 OAuth 2.0凭据:
   • 导航到API和服务>凭据
   • 点击“创建凭据”>“OAuth客户端ID”
   • 选择“桌面应用程序”作为应用程序类型
   • 注意客户端ID和客户端密码

认证

运行auth脚本以设置OAuth凭据：

node auth.js

脚本将：

1. 提示输入您的客户端ID和客户端密码
2. 打开浏览器进入谷歌同意屏幕
3. 监听OAuth回调 http://localhost:3000/callback
4. 将凭据保存到特定于操作系统的默认路径

凭证存储位置：

• 窗户： %APPDATA%\google-calendar-tasks-mcp\credentials.json
• macOS/Linux： ~/.config/google-calendar-tasks-mcp/credentials.json

覆盖 GOOGLE_MCP_CREDENTIALS_PATH 环境变量。

Claude代码配置

添加到您的Claude Code MCP设置（项目级别 .mcp.json 或全局设置）：

{
  "mcpServers": {
    "google-calendar-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/google-calendar-tasks-mcp/build/index.js"],
      "env": {
        "GOOGLE_MCP_TIMEZONE": "America/New_York"
      }
    }
  }
}

工具参考

日历工具

calendar_list_calendars

列出用户有权访问的所有日历。

calendar_list_events

列出日期或日期范围的日历事件。

提供其中之一 date 或两者 startDate 和 endDate.

calendar_get_event

获取单个日历事件的完整详细信息。

calendar_create_event

创建新的日历事件。受护栏约束。

calendar_update_event

更新现有日历事件。受护栏约束。

对于早于以下时间的事件被阻止 pastEventProtectionDays.

calendar_delete_event

删除单个日历事件。受护栏约束。

对于过去的事件和重复出现的系列主控，已被阻止（除非 allowRecurringSeriesDelete 这是真的）。

任务工具

tasks_list_tasklists

列出所有任务列表。

tasks_list

在给定的列表中列出任务。

tasks_get

获取单个任务的完整详细信息。

tasks_create

创建新任务。受护栏约束。

tasks_update

更新现有任务。受护栏约束。

tasks_delete

删除单个任务。受护栏约束。

tasks_complete

将任务标记为已完成。受护栏约束。

tasks_move

将任务移动到其他列表。计为2次写入操作（创建+删除）。受护栏约束。

Gmail工具

gmail_list_messages

搜索并列出电子邮件。

gmail_get_message

获取一封电子邮件的完整内容。

gmail_get_attachment

从电子邮件中下载特定附件。

gmail_modify_message

在电子邮件中添加或删除标签。移除 INBOX 存档。添加 TRASH 垃圾。

受护栏约束。

gmail_list_labels

列出所有Gmail标签（系统和用户创建）。

gmail_create_label

创建一个新的Gmail标签。

受护栏约束。

gmail_send_message

发送电子邮件（回复或新建）。 需要明确批准 — requireApproval 必须 true.

受护栏约束。这 requireApproval: true 标志由服务器强制执行——没有标志的调用将被拒绝。

配置

环境变量

护栏配置

创建或编辑 guardrails.json 在服务器目录中：

{
  "dailyWriteLimit": 50,
  "pastEventProtectionDays": 7,
  "protectedCalendars": [],
  "protectedTaskLists": [],
  "allowRecurringSeriesDelete": false,
  "gmail": {
    "sendRequiresApproval": true,
    "maxSendsPerDay": 10
  }
}

审计日志

通过设置启用 GOOGLE_MCP_AUDIT_LOG_DIR 到目录路径。服务器每月写入JSON文件(operations_YYYY-MM.json)跟踪所有创建、更新、删除、完成和移动操作。

每个条目包括：操作类型、服务、项目标题、Google ID、时间戳和所做的任何更改。

发展

npm run build          # Compile TypeScript
npm test               # Run all tests
npm run test:unit      # Run unit tests only
npm run test:integration  # Run integration tests only
npm run inspect        # Launch MCP Inspector

测试模式

集 GOOGLE_MCP_TEST_MODE=true 使用模拟Google API运行。适用于没有真实证书的开发和测试。

许可证

麻省理工学院