google-tasks-mcp-server

通过 stdio 操纵 Google Tasks 的 MCP 服务器。提供任务列表和任务列表列表的处理（CRUD）、完成状态切换、排序与移动，以及批量隐藏已完成任务。

由于 Google 官方的 Workspace MCP 服务器集合（Gmail / Calendar / Drive（等））也允许以 Tasks 不包含在其中，因此本服务器是为弥补这一缺口而构建的。

设计方针

• 凭据信息以文件形式传入。 部署中指定环境变量中的 client_secret_*.json 的路径，无需在 MCP 配置文件中保存 Client Secret 保存为普通明文。

• 首次认证由独立 CLI 完成。 MCP 服务器和 stdout 原本用于 JSON-RPC 通，若与浏览器启动或日志混杂会破坏协议。将认证分开由登录完成，双方冲突导致的，且便于出错时的问题分类。

• 权限范围只针对 Genie Tasks。 只要求 https://www.googleapis.com/auth/tasks。

• 更新采用 patch 方式。 因为 update 会冲掉未指定的字段，所以部分更新始终使用 patch。

Related MCP server: Mini Task MCP Server

设置

1. 准备 GCP

1. 在 API 与服务 → 库中启用 Google Tasks API。

2. 在 凭据中创建 OAuth 2.0 客户端 ID，应用类型选择 桌面应用。

   • 桌面应用类型可按需要指定任意本地回环端口作为重定向目标，而无需注册重定向 URI。

3. 继续下载 JSON 文件（client_secret_xxx.json）。

4. 若 OAuth 同意屏幕处于“测试”状态，则把自己的 Google 账号添加到测试用户。

2. 构建

npm install
npm run build

3. 首次认证

指定 client_secret_*.json 的路径作为参数。浏览器会打开，请同意授权。

GOOGLE_TASKS_CLIENT_SECRET_PATH=~/path/to/client_secret_xxx.json npm run auth

认证令牌会以来保存文件到 ~/.config/google-tasks-mcp-server/token.json，权限为 0600。此过程会在刷新令牌自动更新，计，因此本步骤只执行首次。

4. 注册到 MCP 客户端

在 Claude Code 中的做法：

claude mcp add google-tasks \
  -e GOOGLE_TASKS_CLIENT_SECRET_PATH=$HOME/path/to/client_secret_xxx.json \
  -- node /absolute/path/to/google-tasks-mcp-server/dist/index.js

直接在 .mcp.json 中写入的情况：

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

环境变量

工具

tasklist 在省略时使用 @default（默认的任务列表）。

任务列表

任务

规格注意事项

• 截止日期不会保留时间。 即使将日期作为 RFC 3339 传入 due，也会被处理为仅保留日期部分。

• 获取完成的任务一定要 showHidden。 Google 会自动排除手动输入的 showCompleted 值。为了在“主客户端已完成的任务”返回时为真，服务器会在 showCompleted: true 时自动补项 showHidden。

• clear-completed-tasks 不是删除。就只是隐藏，使用 showHidden: true 可再次取得。

• 截止日期筛选项会自动修正为“包含指定日”。 因 Google Tasks API 的 dueMax 是按日期单位排除的，即使传入当天的 23:59:59，也不会返回当天到期的任务（需传入次日 0 点）。为了符合直觉，本服务器将 dueMin / dueMax 规范化为日期边界，使两者都变为“包含指定日”的行为。

开发

npm run typecheck   # 型チェックのみ
npm run build       # dist/ に出力
npm run auth        # 初回認証

许可证

MIT

安装脚本

完成 GCP 控制台中的操作（启用 Tasks API、创建桌面应用类型的 OAuth 客户端以及下载 JSON）之后，就可以在文件中集中一次性执行后续步骤。

安装命令:

./scripts/setup.sh

从 ~/Downloads 自动搜索 client_secret*.json，在验证种类型之后，以权限 600 保存到 ~/.config/google-tasks-mcp-server/，并执行构建、首次认证和 MCP 服务器注册。如果是在其他位置，使用确认后传入路径即可。

./scripts/setup.sh /path/to/client_secret.json