Google Tasks MCP Server

Google Tasks MCP 服务

此模型上下文协议（MCP）服务为 MCP 客户端与 Google Tasks 搭建桥梁，让你可以直接通过 Claude Desktop、Cursor 和 Codex 等客户端管理任务列表和任务。

说明

本项目中的所有代码（少量修改除外）都是 "vibe coded" 的——根据我的指示，由 Claude/Copilot 生成。

功能

此 MCP 服务提供以下功能：

任务列表管理

• list-tasklists - 列出所有任务列表
• get-tasklist - 获取特定任务列表的详细信息
• create-tasklist - 创建新的任务列表
• update-tasklist - 更新现有任务列表
• delete-tasklist - 删除任务列表

任务管理

• list-tasks - 列出任务列表中的所有任务，包括分页结果
• get-task - 获取特定任务的详细信息
• create-task - 创建新任务
• update-task - 更新现有任务
• delete-task - 删除任务
• complete-task - 将任务标记为已完成
• move-task - 移动任务（重新排序、更改父级，或在不同任务列表之间移动）
• clear-completed-tasks - 清除列表中的所有已完成任务

设置说明

1. 创建 Google Cloud 项目并启用 API

1. 前往 Google Cloud Console
2. 创建新项目
3. 前往“APIs & Services” > “Library”
4. 搜索“Google Tasks API”并启用
5. 前往“APIs & Services” > “Credentials”
6. 点击“Create Credentials” > “OAuth Client ID”
7. 配置 OAuth 同意屏幕（个人使用时选择 External 即可）
8. 在 Application Type 中选择“Web application”
9. 添加“http://localhost:3000/oauth2callback”作为授权重定向 URI
10. 创建客户端 ID 和密钥

2. 配置环境变量

在此项目目录中创建 .env 文件：

GOOGLE_CLIENT_ID=your_client_id_here
GOOGLE_CLIENT_SECRET=your_client_secret_here
GOOGLE_REDIRECT_URI=http://localhost:3000/oauth2callback

环境变量：

• GOOGLE_CLIENT_ID（必填）- Google OAuth 客户端 ID
• GOOGLE_CLIENT_SECRET（必填）- Google OAuth 客户端密钥
• GOOGLE_REDIRECT_URI（可选）- OAuth 重定向 URI（默认为 http://localhost:3000/oauth2callback）

注意： 服务会在启动时验证是否已设置 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET，如果缺失或无效，会显示明确的错误消息并启动失败。

3. 构建服务

1. 安装依赖：

npm install

2. 构建服务：

npm run build

4. 配置 MCP 客户端

Codex

将服务添加到 ~/.codex/config.toml：

[mcp_servers.google-tasks]
command = "zsh"
args = ["-lc", "cd /path/to/google-tasks-mcp && exec node build/index.js"]

将 /path/to/google-tasks-mcp 替换为此项目的路径，然后重启 Codex。

验证服务是否已注册：

codex mcp list
codex mcp get google-tasks

Claude for Desktop

1. 安装 Claude for Desktop
2. 打开 Claude 配置文件：
   • MacOS：~/Library/Application Support/Claude/claude_desktop_config.json
   • Windows：%APPDATA%\Claude\claude_desktop_config.json
3. 添加 Google Tasks MCP 服务配置：

{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/path/to/google-tasks-mcp/build/index.js"]
    }
  }
}

将路径替换为你自己的路径，然后重启 Claude for Desktop。

身份验证流程

首次使用 Google Tasks MCP 服务时：

1. 使用 authenticate 工具获取授权 URL
2. 在浏览器中访问该 URL，并使用 Google 账号登录
3. 授权后，你会在浏览器页面上收到一个代码
4. 使用 set-auth-code 工具并提供此代码，以完成身份验证
5. 现在，你可以使用所有其他工具与 Google Tasks 交互

注意： 你的身份验证令牌（包括刷新令牌）会自动保存到 ~/.config/google-tasks-mcp/credentials.json，并设置受限权限（600）。这意味着：

• 只需进行一次身份验证——凭据会在服务重启后保留
• 自动刷新令牌——访问令牌过期时（通常为 1 小时后），会使用保存的刷新令牌自动刷新
• 无需重新进行身份验证——完成初始设置后，除非撤销访问权限或删除凭据文件，否则无需再次进行身份验证

要求

• Node.js 20+（参见 package.json 中的 engines）
• 兼容 MCP 的客户端
• 已启用 Tasks API 的 Google Cloud 项目

实现特性

此 MCP 服务包含以下改进：

• 持久化令牌存储——身份验证凭据会保存到磁盘（~/.config/google-tasks-mcp/credentials.json），并设置受限权限，因此只需进行一次身份验证
• 环境变量验证——启动时会验证必需的凭据是否已配置，并提供清晰的错误消息
• 自动刷新令牌——OAuth 令牌过期时会自动刷新，无需在活动会话期间或重启后重新进行身份验证
• 增强的输入验证——全面验证所有输入，包括 ID 格式、字符串长度和 RFC 3339 日期格式
• HTML 清理——对 OAuth 回调响应进行清理，以防止 XSS 漏洞
• 平稳关闭——收到 SIGINT/SIGTERM 信号时妥善清理资源
• 类型安全——整个代码库均具备完整的 TypeScript 类型安全性，并使用恰当的接口
• 可配置的重定向 URI——可通过 GOOGLE_REDIRECT_URI 环境变量自定义 OAuth 重定向 URI

截图

Claude Desktop

Cursor

许可证

此项目仅用于演示。使用风险由你自行承担。