google-tasks

google-tasks-mcp-server

适用于 Google Tasks 的 MCP 服务。为任何 MCP 客户端（Claude Desktop、Claude Code、Codex、Cursor 等）提供对任务清单和任务的完整读写权限：列出、创建、更新、完成、删除和移动任务，并支持真正的到期日期。

Google Tasks 没有官方 MCP 服务，因此本项目填补了这一空缺。支持完整的 CRUD 操作，采用 OAuth 已安装应用身份验证流程（你的凭据不会离开你的设备），全程使用 TypeScript。

工具

任务清单

• google_tasks_list_tasklists 列出所有任务清单
• google_tasks_get_tasklist 获取一个任务清单
• google_tasks_create_tasklist 创建新的任务清单
• google_tasks_update_tasklist 重命名任务清单
• google_tasks_delete_tasklist 删除任务清单及其所有任务

任务

• google_tasks_list_tasks 列出清单中的任务，支持到期日期／更新时间筛选和分页
• google_tasks_get_task 获取一个任务
• google_tasks_create_task 创建任务（可选创建为子任务，也可选指定位置）
• google_tasks_update_task 更新标题／备注／到期日期／状态
• google_tasks_complete_task / google_tasks_reopen_task 将任务标记为已完成／未完成
• google_tasks_delete_task 删除任务
• google_tasks_move_task 重新排序、变更父任务，或将任务移动到其他清单
• google_tasks_clear_completed_tasks 清除清单中的所有已完成任务

每个工具都支持 response_format: "markdown" | "json"。

快速开始

通过 npm 安装：

npm install -g @girmmy/google-tasks-mcp-server

也可以完全不安装，让 MCP 客户端通过 npx 运行（参见步骤 4）。

也可以从源代码运行：

git clone https://github.com/girmmy/google-tasks-mcp-server.git
cd google-tasks-mcp-server
npm install
npm run build

无论采用哪种方式，都请按照下方的设置说明创建自己的 Google OAuth 凭据并完成授权。本项目没有共享或托管版本，而是直接连接到你自己的 Google 账号。

设置

1. 创建 Google Cloud OAuth 客户端

每位用户都需要自己的 OAuth 客户端。客户端无法共享，因为任何使用你的客户端密钥的人都可能冒充你的应用（不过，他们仍然需要每位用户各自的授权）。

1. 前往 Google Cloud Console，创建（或选择）一个项目。
2. APIs & Services → Library → 启用 Google Tasks API。
3. APIs & Services → OAuth consent screen（Google 现在将其称为 “Google Auth Platform”）：
   • User type：个人使用选择 External 即可。
   • 填写应用名称，以及用于支持／联系的电子邮件地址。
   • 在 Audience → Test users 下添加你自己的 Google 账号。应用处于 “Testing” 状态时，只有列出的测试用户才能授权；如果你只是自己使用，这样就可以了。
4. Clients → Create Client → Application type 选择 Desktop app，然后创建客户端。
5. 获取客户端 ID 和客户端密钥：可以在创建后立即选择 “Download JSON” 下载，也可以之后从客户端详情页获取。离开页面后，Google 控制台不会再次显示密钥明文，只能下载或重新生成；如果弄丢了，只需添加一个新密钥，不必费力寻找旧密钥。
6. 保存该文件。默认情况下，此服务会在以下位置查找： ~/.config/google-tasks-mcp-server/client_secret.json （可通过 GOOGLE_TASKS_CLIENT_SECRET 环境变量覆盖路径；如果你更希望将其保存在项目目录中，例如 ./credentials/client_secret.json，这会很有用。credentials/ 已加入 gitignore。）

该文件应如下所示：

{
  "installed": {
    "client_id": "YOUR_CLIENT_ID.apps.googleusercontent.com",
    "client_secret": "YOUR_CLIENT_SECRET",
    "auth_uri": "https://accounts.google.com/o/oauth2/auth",
    "token_uri": "https://oauth2.googleapis.com/token",
    "redirect_uris": ["http://localhost"]
  }
}

2. 安装

通过 npm 安装（无需构建）：

npm install -g @girmmy/google-tasks-mcp-server

从源代码安装：

npm install
npm run build

3. 授权（一次性）

如果你通过 npm 安装：

google-tasks-mcp-auth
# or without installing anything:
npx -y -p @girmmy/google-tasks-mcp-server google-tasks-mcp-auth

从源码安装：

npm run auth
# or, if your client secret lives at a custom path:
GOOGLE_TASKS_CLIENT_SECRET=./credentials/client_secret.json npm run auth

这会输出一个 Google 同意授权网址，并尝试在默认浏览器中打开。登录并授予访问权限后，页面会重定向回一个短暂运行的本地服务 http://localhost:53682。令牌会缓存到 ~/.config/google-tasks-mcp-server/token.json（可通过 GOOGLE_TASKS_TOKEN_PATH 覆盖），之后会自动刷新，因此除非你撤销访问权限，否则无需再次运行此步骤。

请在你日常实际使用的同一台机器和同一个常规终端中运行此命令。如果你是在容器、虚拟机或沙盒 shell 中运行，导致 localhost 无法连接回浏览器，请参阅下方的故障排除。

4. 运行

npm start

也可以将其接入 MCP 客户端。对于 Claude Desktop / Claude Code，请将其添加到 MCP 配置中（macOS 上通常为 ~/Library/Application Support/Claude/claude_desktop_config.json）。

使用 npm，且客户端密钥位于默认的 ~/.config/... 路径时，完整配置如下：

{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": ["-y", "@girmmy/google-tasks-mcp-server"]
    }
  }
}

或者指向源码检出目录：

{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/google-tasks-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_TASKS_CLIENT_SECRET": "/absolute/path/to/google-tasks-mcp-server/credentials/client_secret.json"
      }
    }
  }
}

如果客户端密钥保存在默认的 ~/.config/... 路径中，请省略 env 块。之后请完全退出并重新打开 MCP 客户端。

Codex

Codex 使用 TOML，而非 JSON。将以下内容添加到 ~/.codex/config.toml：

[mcp_servers.google-tasks]
command = "npx"
args = ["-y", "@girmmy/google-tasks-mcp-server"]
startup_timeout_sec = 60

也可以让 CLI 为你写入配置：

codex mcp add google-tasks -- npx -y @girmmy/google-tasks-mcp-server

如果首次启动超时，请调高 startup_timeout_sec。冷启动时，npx 会先下载软件包，然后服务才能响应 initialize；而 Codex 默认的等待时间较短，因此有时只会在首次运行时触发超时。

如果客户端密钥不在默认路径，请添加：

[mcp_servers.google-tasks.env]
GOOGLE_TASKS_CLIENT_SECRET = "/absolute/path/to/client_secret.json"

使用 codex mcp list 检查是否已注册。授权步骤与其他情况相同，都是一次性的 google-tasks-mcp-auth——请在常规终端中运行，而不是在 Codex 中运行，因为该步骤需要打开浏览器并接收环回重定向。

环境变量

变量	默认值	用途
GOOGLE_TASKS_CLIENT_SECRET	~/.config/google-tasks-mcp-server/client_secret.json	已下载的 OAuth 客户端 JSON 文件路径
GOOGLE_TASKS_TOKEN_PATH	~/.config/google-tasks-mcp-server/token.json	缓存的 OAuth 令牌存储路径
GOOGLE_TASKS_OAUTH_PORT	53682	仅在 npm run auth 期间使用的环回端口

安全说明

• 客户端密钥和缓存令牌以普通文件形式存储在磁盘上（令牌的权限模式为 0600）。切勿提交这些文件（.gitignore 已排除 client_secret*.json、token.json、credentials/）。
• 服务会请求完整的 https://www.googleapis.com/auth/tasks 范围（读写）。如需只读访问，请在运行 npm run auth 前，将 src/constants.ts 中的 TASKS_SCOPE 编辑为 .../auth/tasks.readonly。之后写入工具会因 Google 返回 403 而失败，这是预期行为。
• 工具注解将删除/清除操作标记为 destructiveHint: true，以便 MCP 客户端发出警告或对其进行限制。
• 此处的任何内容都不会与 Google 自有 API 以外的服务通信；在运行 npm run auth 期间，唯一额外通信对象是本地环回监听器。不涉及任何第三方后端。

故障排除

npm run auth 打开了一个 URL，我点击“允许”后，进程就一直卡着。 运行 npm run auth 的进程与您点击“允许”时使用的浏览器不在同一台机器或网络上。如果您在容器、远程开发环境或隔离了 localhost 的沙盒 shell 中运行服务，就很可能遇到这种情况。解决方法：在您使用的浏览器所在机器上，通过普通的本地终端直接运行 npm run auth。

Error [TransformError] ... You installed esbuild for another platform 您的 node_modules 是在与当前运行环境不同的操作系统或架构上安装的，例如从 Docker 容器或另一台机器复制而来。解决方法：rm -rf node_modules package-lock.json && npm install。

Authorization failed: invalid_client 您的 client_secret.json 中的客户端密钥有误，通常是因为手动复制粘贴，而不是直接下载。返回 Google Cloud Console，添加新的客户端密钥，直接下载或复制，然后更新 client_secret.json。

服务立即退出，并显示“未找到缓存的 Google Tasks 令牌” 您尚未完成授权，或授权流程未完成。启动服务前，请运行 google-tasks-mcp-auth（npm install）或 npm run auth（source checkout）。

开发

npm run dev     # run directly from TypeScript with auto-reload
npm run build   # type-check and compile to dist/

使用 MCP Inspector 进行测试：

npx @modelcontextprotocol/inspector node dist/index.js

贡献

欢迎提交问题和 PR。此项目涵盖完整的 Tasks API，但尚未针对所有边缘情况进行测试，因此如果您遇到错误或希望添加功能，请提交问题。

许可证

MIT，详见 LICENSE。