
Google Tasks MCP Server
io.github.ebmurha由 GitHub 账号 ebmurha 发布v0.4.0更新于 Nov 10, 2026
Manage Google Tasks from MCP-compatible AI clients.
概览
自托管的 MCP 服务器,让助手读取、搜索、汇总并修改你自己 Google 账号中的 Google Tasks。
- 可以做什么
- 列出、创建、获取、更新和删除任务列表,删除需确认
- 读取某个任务列表中的任务并列出任务
- 通过今日、逾期、即将到期、搜索和摘要视图跨列表汇总任务
- 添加、完成、取消完成、更新、删除、移动任务以及清除已完成任务
- 支持本地 stdio 或流式 HTTP,HTTP 可用 Bearer 令牌或可选 OAuth 网关认证
- 适用场景
- 当你希望 AI 客户端帮你梳理和编辑 Google Tasks——查看今天到期或已逾期的任务、搜索任务、新建或勾选完成条目——同时把凭据和数据留在自己掌控的基础设施上时使用。
- 运行要求
- 需要 Python 3.11 并在本地安装该包,或部署为托管 HTTP 服务。需要一个启用 Tasks API 的 Google Cloud 项目及 OAuth 客户端,通过 GOOGLE_CLIENT_ID、GOOGLE_CLIENT_SECRET 和 GOOGLE_REDIRECT_URI(或客户端 JSON 路径)配置。每个 Google 账号需执行一次引导授权。HTTP 模式需要 MCP_BEARER_TOKEN;令牌与 OAuth 状态需要持久化的 DB_PATH。
安装
在 SourceWeft 中
- 打开 控制台中的 Google Tasks MCP Server,将其添加到工作区。
- 为需要使用其工具的对话启用该服务。
Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。
其他 MCP 客户端
参照 仓库 中的启动说明。
README
Google Tasks MCP Server
Connect an MCP-compatible client to Google Tasks through a private server you run yourself. The server exposes compact tools for reading, searching, summarizing, creating, completing, updating, deleting, and moving Google Tasks.
This project is for self-hosted use. You provide your own Google Cloud OAuth credentials, connect your own Google account, and keep tokens in your own SQLite database.
What You Get
- 19 MCP tools for Google Tasks.
- Local stdio mode for desktop/client-launched setups.
- Streamable HTTP mode for local HTTP or VPS hosting.
- Bearer-token HTTP auth, plus optional OAuth 2.0 gateway mode for MCP clients that support OAuth.
- Compact responses designed for low-context assistant workflows.
- Optional operator-managed multi-account bearer-token routing, for familiar setups such as one personal account and one work account.
Choose A Transport
For deeper hosting and distribution guidance, see MCP_SERVER_GUIDE.md and DISTRIBUTION.md.
Container persistence
For a bearer-only single-account HTTP deployment whose filesystem is recreated on startup,
GOOGLE_REFRESH_TOKEN can seed an empty SQLite database. It never overwrites an
existing token. Keep it in the hosting provider's secret store; do not put it
in a start command or Docker build argument. Hosts that provide PORT can use
it when BIND_PORT is unset.
OAuth gateway deployments also persist dynamically registered clients and MCP refresh-token hashes. Configure the image's Litestream variables to restore and replicate SQLite to an S3-compatible bucket when the host filesystem is disposable. The container restores the database before starting the server and replicates changes while it runs.
Install
Generate a bearer token if you will run HTTP mode:
Put the generated value in .env as MCP_BEARER_TOKEN. Do not commit .env.
Google Cloud Setup
- Create or open a Google Cloud project.
- Enable the Google Tasks API.
- Configure the OAuth consent screen.
- Create an OAuth 2.0 Client ID.
Recommended for local HTTP, VPS, Docker, and other server-style installs:
- Application type: Web application
- Local redirect URI:
http://127.0.0.1:8787/callback - Hosted redirect URI:
https://your-domain.example/callback .env: setGOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET, andGOOGLE_REDIRECT_URI
Local-only alternative:
- Application type: Desktop app
- Download the OAuth client JSON outside this repo.
- Set
GOOGLE_OAUTH_KEYS_PATHto that file path. - Leave
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETempty unless you want env vars to override the JSON file.
Example .env for a local web OAuth client:
If the Google OAuth app is in Testing mode, add every Google account you bootstrap as a test user, such as both personal and work accounts.
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_OAUTH_KEYS_PATH identify the Google Cloud OAuth app, not the Google Tasks user account. One OAuth client JSON can be reused for several Google users. Each bootstrap run stores a separate refresh token for the Google account you authorize in the browser.
Bootstrap Google OAuth
Hosted HTTP onboarding
For a hosted server, set these independently chosen values:
Configure the public URLs explicitly. The application serves the exact paths
from GOOGLE_OAUTH_ONBOARDING_URL and GOOGLE_REDIRECT_URI; it does not retain
root-path aliases. The MCP gateway likewise serves the paths declared by
MCP_OAUTH_ISSUER and MCP_OAUTH_RESOURCE. A reverse proxy forwards these
public paths unchanged. The displayed onboarding link never contains the setup
secret.
OAuth-capable MCP clients use one continuous Connect or Reconnect flow. After the server's MCP consent is approved, it verifies the configured Google account. A usable Google credential continues directly to the MCP client. A missing or rejected Google credential continues through Google consent, stores the Google token in SQLite, and then returns to the same MCP client with its original OAuth state and PKCE binding. No token is displayed or copied.
GOOGLE_OAUTH_ONBOARDING_URL remains a separately password-protected recovery
page. Open it directly only when explicit operator recovery is needed. If an
authenticated MCP tool finds no usable Google token, its error includes this
safe recovery URL.
Local and recovery CLI
Run this once per Google account you want the server to access:
Open the printed URL, approve access, and paste the authorization code back into the terminal.
For multiple trusted accounts on one HTTP server, create one stored bearer token per account and bootstrap each account separately:
Use each printed bearer token only in the matching account's MCP client. The server stores only bearer-token hashes.
Start The Server
HTTP mode:
Health check:
Expected response:
Stdio mode:
Configuration check:
Connect An MCP Client
Remote or local HTTP:
For a VPS, replace the URL with your HTTPS endpoint:
Local stdio:
MCP_BEARER_TOKEN is not required for stdio because the MCP client launches the process locally.
Authentication Modes
Bearer-token mode is the default HTTP mode. /mcp requires Authorization: Bearer <token>.
MCP_BEARER_TOKENroutes to accountdefault.- Tokens created with
google-tasks-mcp-create-bearer-tokencan route different clients to differentaccount_idvalues. - Bearer tokens are displayed once and stored only as hashes.
OAuth 2.0 gateway mode is optional. Enable it when your HTTP MCP client supports OAuth authorization metadata and token refresh.
- Set
MCP_OAUTH_ISSUER,MCP_OAUTH_CLIENT_ID,MCP_OAUTH_CLIENT_SECRET, andMCP_OAUTH_SIGNING_SECRET. - Set
MCP_OAUTH_RESOURCEto the canonical public MCP URL, or let it default to<issuer>/mcp. - Set
MCP_OAUTH_REDIRECT_URISto the callback URI values accepted by your MCP client. - Set
MCP_OAUTH_ENABLE_DCR=truefor clients that use Dynamic Client Registration. - The gateway publishes protected-resource and authorization-server metadata,
requires PKCE
S256, binds tokens to the canonical resource, and includes RFC 9207 issuer identification in authorization redirects. /mcpaccepts OAuth-issued access tokens and the legacy bearer token.- OAuth client secrets and refresh tokens are stored only by hash. Registered
clients and rotating refresh tokens survive restarts when
DB_PATHis durable.
The public proxy URL, MCP OAuth issuer/resource, and Google OAuth callback are operator-controlled deployment settings. They may be changed independently. The server does not require a particular hostname or derive these choices from an owner-specific URL.
MCP OAuth authenticates the client to this server. Google OAuth independently authorizes this server to call Google Tasks. The MCP consent flow coordinates the two layers so Connect and Reconnect cannot finish successfully while the configured Google account is knowingly unusable. The standalone operator page remains available for explicit recovery.
Leave MCP_OAUTH_REDIRECT_URIS empty to keep OAuth gateway mode disabled.
Tools
The same 19 tools are available over stdio, bearer-token HTTP, and OAuth gateway HTTP modes. Tools expose standard MCP titles, descriptions, and safety hints where the client supports them.
All tasklist arguments accept a tasklist ID or exact title. Task title lookup is exact after trimming whitespace and ignores case.
For today, overdue, upcoming, search, and digest, omitting tasklist reads every tasklist. Returned task objects include tasklist_id and tasklist_title; digest labels items with tasklist context.
For list_tasks, clear_completed, single-task tools, and write tools, omitting tasklist uses DEFAULT_TASKLIST, or the first list returned by Google. This prevents unqualified writes from touching every list.
Limitations
These are Google Tasks REST API limits:
- Due dates are date-only. Google drops time-of-day values on task due dates.
- Recurring tasks cannot be created or read through the Google Tasks REST API.
clear_completedhides completed tasks; it does not permanently delete them.
Docker And VPS
Docker:
Keep .env, OAuth JSON files, and SQLite databases outside images and public bundles.
VPS/systemd/Caddy templates are in deploy/:
Replace every placeholder domain, path, and user before deploying.
Troubleshooting
Missing bearer token:
- HTTP
/mcprequiresAuthorization: Bearer <token>unless OAuth gateway mode is handling the client. - Stdio mode does not use
MCP_BEARER_TOKEN.
Google OAuth app is in Testing mode:
- Add every bootstrapped Google user as a test user.
- Testing-mode refresh tokens can expire after 7 days.
Callback URI mismatch:
GOOGLE_REDIRECT_URImust exactly match an Authorized redirect URI in Google Cloud.- For local web OAuth, use
http://127.0.0.1:8787/callbackconsistently.
Expired or revoked Google refresh token:
- For hosted HTTP, open
GOOGLE_OAUTH_ONBOARDING_URLand reconnect Google. - For local or recovery use, run
google-tasks-mcp-bootstrapagain. - For multi-account mode, include the same
--account-idyou used before.
OAuth MCP client keeps re-authorizing:
- Ensure the server is running a version with persisted MCP OAuth refresh tokens.
- Check that
DB_PATHpoints to persistent storage and survives restarts. - Verify
MCP_OAUTH_ISSUERis the public HTTPS base URL with no trailing slash. - Verify
MCP_OAUTH_RESOURCEmatches the public/mcpURL exactly. - On disposable hosts, verify Litestream restored the SQLite replica before startup.
More Docs
- MCP_SERVER_GUIDE.md explains hosting models, credential boundaries, and public project vs public service choices.
- DISTRIBUTION.md explains registry, bundle, and directory publishing.
- .env.example lists every supported environment variable.
- google-tasks-mcp-specifications.md is the behavioral source of truth.
Tests
来源:README.md,提交 4948e10
工具
0版本历史
1- v0.4.0最新Sep 16, 2026
评分
已满足适用检查项的 50%
该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。
- 近 30 天内可连通25 分
请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。
- 已声明认证方式10 分
请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。
- 已列出工具15 分
请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。
- 描述必需15 分
- 图标10 分
- 文档15 分
- 许可证10 分