The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Google Tasks MCP Server listing page.
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.
| Use case | Transport | Auth |
|---|---|---|
| MCP client starts the process directly | stdio | No MCP_BEARER_TOKEN needed |
| Local HTTP server | Streamable HTTP at http://127.0.0.1:8787/mcp | Bearer token |
| VPS or other host | Streamable HTTP at https://your-domain.example/mcp | Bearer token or OAuth gateway |
For deeper hosting and distribution guidance, see MCP_SERVER_GUIDE.md and DISTRIBUTION.md.
Generate a bearer token if you will run HTTP mode:
Put the generated value in .env as MCP_BEARER_TOKEN. Do not commit .env.
Recommended for local HTTP, VPS, Docker, and other server-style installs:
http://127.0.0.1:8787/callbackhttps://your-domain.example/callback.env: set GOOGLE_CLIENT_ID, GOOGLE_CLIENT_SECRET, and GOOGLE_REDIRECT_URILocal-only alternative:
GOOGLE_OAUTH_KEYS_PATH to that file path.GOOGLE_CLIENT_ID and GOOGLE_CLIENT_SECRET empty 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.
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.
HTTP mode:
Health check:
Expected response:
Stdio mode:
Configuration check:
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.
Bearer-token mode is the default HTTP mode. /mcp requires Authorization: Bearer <token>.
MCP_BEARER_TOKEN routes to account default.google-tasks-mcp-create-bearer-token can route different clients to different account_id values.OAuth 2.0 gateway mode is optional. Enable it when your HTTP MCP client supports OAuth authorization metadata and token refresh.
MCP_OAUTH_ISSUER, MCP_OAUTH_CLIENT_ID, MCP_OAUTH_CLIENT_SECRET, and MCP_OAUTH_SIGNING_SECRET.MCP_OAUTH_REDIRECT_URIS to the callback URI values accepted by your MCP client./mcp accepts OAuth-issued access tokens and the legacy bearer token.Leave MCP_OAUTH_REDIRECT_URIS empty to keep OAuth gateway mode disabled.
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.
| Group | Tools | Notes |
|---|---|---|
| Tasklists | list_tasklists, create_tasklist, get_tasklist, update_tasklist, delete_tasklist | Tasklist delete requires confirm: true; non-empty lists require force: true. |
| Task reads | list_tasks, get_task | Read from one tasklist. If tasklist is omitted, uses DEFAULT_TASKLIST or Google's first list. |
| Task summaries | today, overdue, upcoming, search, digest | If tasklist is omitted, reads all tasklists and includes tasklist context. |
| Task mutations | clear_completed, add, complete, update, uncomplete, delete, move | Mutate one tasklist/task at a time. clear_completed requires confirm: true. |
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.
These are Google Tasks REST API limits:
clear_completed hides completed tasks; it does not permanently delete them.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.
Missing bearer token:
/mcp requires Authorization: Bearer <token> unless OAuth gateway mode is handling the client.MCP_BEARER_TOKEN.Google OAuth app is in Testing mode:
Callback URI mismatch:
GOOGLE_REDIRECT_URI must exactly match an Authorized redirect URI in Google Cloud.http://127.0.0.1:8787/callback consistently.Expired or revoked Google refresh token:
google-tasks-mcp-bootstrap again for the affected account.--account-id you used before.OAuth MCP client keeps re-authorizing:
DB_PATH points to persistent storage and survives restarts.MCP_OAUTH_ISSUER is the public HTTPS base URL with no trailing slash.