Google Tasks MCP Server

Google Tasks MCP 服务

将兼容 MCP 的客户端连接到由你自行运行的私有服务，以使用 Google Tasks。该服务提供精简的工具，用于读取、搜索、汇总、创建、完成、更新、删除和移动 Google Tasks。

本项目供可自托管使用。你需要提供自己的 Google Cloud OAuth 凭据，连接自己的 Google 账号，并将令牌保存在自己的 SQLite 数据库中。

你将获得

• 19 个用于 Google Tasks 的 MCP 工具。
• 适用于桌面端／客户端启动配置的本地 stdio 模式。
• 适用于本地 HTTP 或 VPS 托管的 Streamable HTTP 模式。
• Bearer 令牌 HTTP 身份验证，以及可选的 OAuth 2.0 网关模式，供支持 OAuth 的 MCP 客户端使用。
• 为低上下文助手工作流设计的精简响应。
• 可选的由运营者管理的多账号 Bearer 令牌路由，适用于一个个人账号和一个工作账号等常见配置。

选择传输方式

用例	传输方式	身份验证
MCP 客户端直接启动进程	stdio	无需 MCP_BEARER_TOKEN
本地 HTTP 服务	http://127.0.0.1:8787/mcp 上的 Streamable HTTP	Bearer 令牌
VPS 或其他主机	https://your-domain.example/mcp 上的 Streamable HTTP	Bearer 令牌或 OAuth 网关

有关更深入的托管和分发指南，请参阅 MCP_SERVER_GUIDE.md 和 DISTRIBUTION.md。

容器持久化

对于文件系统在启动时会重建、仅使用 Bearer 令牌且采用单账号的 HTTP 部署， GOOGLE_REFRESH_TOKEN 可用于为全新的 SQLite 数据库填充初始令牌。它不会覆盖 已有令牌。请将其保存在托管服务提供商的密钥存储中；不要将其放入 启动命令或 Docker 构建参数中。提供 PORT 的主机可在未设置 BIND_PORT 时使用该变量。

OAuth 网关部署还会持久化动态注册的客户端和 MCP 刷新令牌哈希。如果主机文件系统 是临时的，请配置镜像的 Litestream 变量，将 SQLite 恢复并 复制到兼容 S3 的存储桶。容器会在启动服务前恢复数据库， 并在运行期间复制变更。

安装

git clone https://github.com/ebmurha/google-tasks-mcp.git
cd google-tasks-mcp
python3.11 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env

如果要运行 HTTP 模式，请生成 Bearer 令牌：

python -c "import secrets; print(secrets.token_urlsafe(48))"

将生成的值填入 .env 中的 MCP_BEARER_TOKEN。不要提交 .env。

Google Cloud 设置

1. 创建或打开 Google Cloud 项目。
2. 启用 Google Tasks API。
3. 配置 OAuth 同意屏幕。
4. 创建 OAuth 2.0 Client ID。

本地 HTTP、VPS、Docker 及其他服务端式安装的推荐配置：

• 应用类型：Web 应用
• 本地重定向 URI：http://127.0.0.1:8787/callback
• 托管环境重定向 URI：https://your-domain.example/callback
• .env：设置 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 和 GOOGLE_REDIRECT_URI

仅限本地的替代方案：

• 应用类型：桌面应用
• 将 OAuth 客户端 JSON 下载到此仓库之外。
• 将 GOOGLE_OAUTH_KEYS_PATH 设置为该文件的路径。
• 除非要让环境变量覆盖 JSON 文件中的值，否则将 GOOGLE_CLIENT_ID 和 GOOGLE_CLIENT_SECRET 留空。

本地 Web OAuth 客户端的 .env 示例：

GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://127.0.0.1:8787/callback
MCP_BEARER_TOKEN=your-generated-token
DB_PATH=./google-tasks.db
BIND_HOST=127.0.0.1
BIND_PORT=8787

如果 Google OAuth 应用处于 Testing 模式，请将你用于初始化的每个 Google 账号添加为测试用户，例如个人账号和工作账号。

GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_OAUTH_KEYS_PATH 用于标识 Google Cloud OAuth 应用，而非 Google Tasks 用户账号。同一个 OAuth 客户端 JSON 可供多个 Google 用户重复使用。每次初始化运行都会为你在浏览器中授权的 Google 账号单独保存一个刷新令牌。

初始化 Google OAuth

托管 HTTP 上线

对于托管服务，请分别设置以下值：

GOOGLE_REDIRECT_URI=https://your-domain.example/callback
GOOGLE_OAUTH_ONBOARDING_URL=https://your-domain.example/google/oauth
GOOGLE_OAUTH_SETUP_SECRET=generate-a-long-random-operator-password

明确配置公开 URL。应用会提供 GOOGLE_OAUTH_ONBOARDING_URL 和 GOOGLE_REDIRECT_URI 中指定的确切路径；不会保留根路径别名。MCP 网关同样会提供 MCP_OAUTH_ISSUER 和 MCP_OAUTH_RESOURCE 中声明的路径。反向代理会原样转发这些公开路径。显示的上线链接绝不会包含设置密钥。

支持 OAuth 的 MCP 客户端使用连续的连接或重新连接流程。服务器的 MCP 授权获得批准后，会验证已配置的 Google 账号。若 Google 凭据可用，则直接继续连接 MCP 客户端。若缺少或拒绝 Google 凭据，则继续进行 Google 授权，将 Google 令牌存储在 SQLite 中，然后带着原始 OAuth 状态和 PKCE 绑定返回同一 MCP 客户端。不会显示或复制任何令牌。

GOOGLE_OAUTH_ONBOARDING_URL 仍是受独立密码保护的恢复页面。仅在需要运维人员明确执行恢复时，才直接打开此页面。如果经过身份验证的 MCP 工具找不到可用的 Google 令牌，其错误信息会包含此安全恢复 URL。

本地和恢复 CLI

对于希望服务器访问的每个 Google 账号，运行一次：

google-tasks-mcp-bootstrap

打开打印出的 URL，批准访问，然后将授权码粘贴回终端。

对于同一 HTTP 服务器上的多个受信任账号，请为每个账号创建一个已存储的 bearer 令牌，并分别为每个账号进行引导：

google-tasks-mcp-create-bearer-token --account-id personal --label "Personal account"
google-tasks-mcp-bootstrap --account-id personal

google-tasks-mcp-create-bearer-token --account-id work --label "Work account"
google-tasks-mcp-bootstrap --account-id work

每个打印出的 bearer 令牌只能用于对应账号的 MCP 客户端。服务器只存储 bearer 令牌的哈希值。

启动服务器

HTTP 模式：

python -m google_tasks_mcp --transport http

健康检查：

curl http://127.0.0.1:8787/healthz

预期响应：

{"ok": true}

Stdio 模式：

python -m google_tasks_mcp --transport stdio

配置检查：

python -m google_tasks_mcp --check

连接 MCP 客户端

远程或本地 HTTP：

URL:  http://127.0.0.1:8787/mcp
Auth: Bearer <MCP_BEARER_TOKEN>

对于 VPS，请将 URL 替换为你的 HTTPS 端点：

URL:  https://your-domain.example/mcp
Auth: Bearer <MCP_BEARER_TOKEN>

本地 stdio：

{
  "command": "/path/to/google-tasks-mcp/.venv/bin/python",
  "args": ["-m", "google_tasks_mcp", "--transport", "stdio"]
}

对于 stdio，无需设置 MCP_BEARER_TOKEN，因为 MCP 客户端会在本地启动该进程。

身份验证模式

Bearer 令牌模式是默认的 HTTP 模式。/mcp 需要 Authorization: Bearer <token>。

• MCP_BEARER_TOKEN 路由到账号 default。
• 使用 google-tasks-mcp-create-bearer-token 创建的令牌可以将不同客户端路由到不同的 account_id 值。
• Bearer 令牌仅显示一次，且只以哈希形式存储。

OAuth 2.0 网关模式为可选模式。当 HTTP MCP 客户端支持 OAuth 授权元数据和令牌刷新时，可启用此模式。

• 设置 MCP_OAUTH_ISSUER、MCP_OAUTH_CLIENT_ID、MCP_OAUTH_CLIENT_SECRET 和 MCP_OAUTH_SIGNING_SECRET。
• 将 MCP_OAUTH_RESOURCE 设置为规范的公共 MCP URL，或使用默认值 <issuer>/mcp。
• 将 MCP_OAUTH_REDIRECT_URIS 设置为 MCP 客户端接受的回调 URI 值。
• 对于使用动态客户端注册的客户端，设置 MCP_OAUTH_ENABLE_DCR=true。
• 网关会发布受保护资源和授权服务器元数据， 要求使用 PKCE S256，将令牌绑定到规范资源，并在授权重定向中包含 RFC 9207 发行者标识。
• /mcp 接受 OAuth 签发的访问令牌和旧版 Bearer 令牌。
• OAuth 客户端密钥和刷新令牌仅以哈希形式存储。使用持久化的 DB_PATH 时，已注册 的客户端和轮换后的刷新令牌会在重启后保留。

公共代理 URL、MCP OAuth 发行者/资源以及 Google OAuth 回调均由 运维人员控制的部署设置决定。它们可以独立更改。 服务器不要求使用特定主机名，也不会根据 所有者专属的 URL 推导这些设置。

MCP OAuth 用于验证客户端对本服务器的身份。Google OAuth 则独立授权 本服务器调用 Google Tasks。MCP 同意流程会协调这两个层面，确保在已知 配置的 Google 账号不可用时，连接和重新连接都无法成功完成。独立的运维人员页面 仍可用于显式恢复。

将 MCP_OAUTH_REDIRECT_URIS 留空，即可保持 OAuth 网关模式禁用。

工具

在 stdio、Bearer 令牌 HTTP 和 OAuth 网关 HTTP 模式下，均可使用相同的 19 个工具。客户端支持时，工具会提供标准 MCP 标题、描述和安全提示。

分组	工具	说明
任务列表	list_tasklists、create_tasklist、get_tasklist、update_tasklist、delete_tasklist	删除任务列表需要 confirm: true；非空列表还需要 force: true。
任务读取	list_tasks、get_task	从一个任务列表读取。如果省略 tasklist，则使用 DEFAULT_TASKLIST 或 Google 返回的第一个列表。
任务摘要	today、overdue、upcoming、search、digest	如果省略 tasklist，则读取所有任务列表并包含任务列表上下文。
任务修改	clear_completed、add、complete、update、uncomplete、delete、move	每次修改一个任务列表/任务。clear_completed 需要 confirm: true。

所有 tasklist 参数均接受任务列表 ID 或完全匹配的标题。任务标题查找会先去除首尾空白，再进行精确匹配，且不区分大小写。

对于 today、overdue、upcoming、search 和 digest，省略 tasklist 时会读取所有任务列表。返回的任务对象包含 tasklist_id 和 tasklist_title；digest 会为条目标注任务列表上下文。

对于 list_tasks、clear_completed、单任务工具和写入工具，省略 tasklist 时会使用 DEFAULT_TASKLIST，或使用 Google 返回的第一个列表。这可以防止未指定目标的写入操作影响所有列表。

限制

这些限制来自 Google Tasks REST API：

• 截止日期仅包含日期。Google 会丢弃任务截止日期中的时间值。
• 无法通过 Google Tasks REST API 创建或读取重复任务。
• clear_completed 会隐藏已完成的任务；不会永久删除它们。

Docker 和 VPS

Docker：

docker compose up --build

将 .env、OAuth JSON 文件和 SQLite 数据库保存在镜像和公开资源包之外。

VPS/systemd/Caddy 模板位于 deploy/：

• deploy/caddy/Caddyfile
• deploy/systemd/google-tasks-mcp.service

部署前，请替换所有占位域名、路径和用户。

故障排查

缺少 bearer token：

• HTTP /mcp 需要 Authorization: Bearer <token>，除非 OAuth 网关模式正在处理客户端。
• Stdio 模式不使用 MCP_BEARER_TOKEN。

Google OAuth 应用处于 Testing 模式：

• 将每位已完成引导的 Google 用户添加为测试用户。
• Testing 模式的刷新令牌可能会在 7 天后过期。

回调 URI 不匹配：

• GOOGLE_REDIRECT_URI 必须与 Google Cloud 中的 Authorized redirect URI 完全匹配。
• 对于本地 Web OAuth，请始终使用 http://127.0.0.1:8787/callback。

Google 刷新令牌已过期或被撤销：

• 对于托管 HTTP，请打开 GOOGLE_OAUTH_ONBOARDING_URL 并重新连接 Google。
• 对于本地使用或恢复，请再次运行 google-tasks-mcp-bootstrap。
• 对于多账户模式，请传入之前使用的同一个 --account-id。

OAuth MCP 客户端不断重新授权：

• 确保服务运行的是支持持久化 MCP OAuth 刷新令牌的版本。
• 检查 DB_PATH 是否指向持久化存储，并且在重启后仍然存在。
• 确认 MCP_OAUTH_ISSUER 是不带尾部斜杠的公共 HTTPS 基础 URL。
• 确认 MCP_OAUTH_RESOURCE 与公共 /mcp URL 完全匹配。
• 在临时主机上，确认 Litestream 在启动前已恢复 SQLite 副本。

更多文档

• MCP_SERVER_GUIDE.md 介绍托管模式、凭据边界，以及公开项目与公开服务之间的选择。
• DISTRIBUTION.md 介绍注册表、资源包和目录发布。
• .env.example 列出了所有受支持的环境变量。
• google-tasks-mcp-specifications.md 是行为规范的权威依据。

测试

pytest