{
  "markdown": "# Google Tasks MCP Server\n\n<!-- mcp-name: io.github.ebmurha/google-tasks-mcp -->\n\nConnect 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.\n\nThis 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.\n\n## What You Get\n\n- 19 MCP tools for Google Tasks.\n- Local stdio mode for desktop/client-launched setups.\n- Streamable HTTP mode for local HTTP or VPS hosting.\n- Bearer-token HTTP auth, plus optional OAuth 2.0 gateway mode for MCP clients that support OAuth.\n- Compact responses designed for low-context assistant workflows.\n- Optional operator-managed multi-account bearer-token routing, for familiar setups such as one personal account and one work account.\n\n## Choose A Transport\n\n| Use case | Transport | Auth |\n| --- | --- | --- |\n| MCP client starts the process directly | `stdio` | No `MCP_BEARER_TOKEN` needed |\n| Local HTTP server | Streamable HTTP at `http://127.0.0.1:8787/mcp` | Bearer token |\n| VPS or other host | Streamable HTTP at `https://your-domain.example/mcp` | Bearer token or OAuth gateway |\n\nFor deeper hosting and distribution guidance, see [MCP_SERVER_GUIDE.md](./MCP_SERVER_GUIDE.md) and [DISTRIBUTION.md](./DISTRIBUTION.md).\n\n## Install\n\n```bash\ngit clone https://github.com/ebmurha/google-tasks-mcp.git\ncd google-tasks-mcp\npython3.11 -m venv .venv\n. .venv/bin/activate\npip install -e .\ncp .env.example .env\n```\n\nGenerate a bearer token if you will run HTTP mode:\n\n```bash\npython -c \"import secrets; print(secrets.token_urlsafe(48))\"\n```\n\nPut the generated value in `.env` as `MCP_BEARER_TOKEN`. Do not commit `.env`.\n\n## Google Cloud Setup\n\n1. Create or open a Google Cloud project.\n2. Enable the Google Tasks API.\n3. Configure the OAuth consent screen.\n4. Create an OAuth 2.0 Client ID.\n\nRecommended for local HTTP, VPS, Docker, and other server-style installs:\n\n- Application type: **Web application**\n- Local redirect URI: `http://127.0.0.1:8787/callback`\n- Hosted redirect URI: `https://your-domain.example/callback`\n- `.env`: set `GOOGLE_CLIENT_ID`, `GOOGLE_CLIENT_SECRET`, and `GOOGLE_REDIRECT_URI`\n\nLocal-only alternative:\n\n- Application type: **Desktop app**\n- Download the OAuth client JSON outside this repo.\n- Set `GOOGLE_OAUTH_KEYS_PATH` to that file path.\n- Leave `GOOGLE_CLIENT_ID` and `GOOGLE_CLIENT_SECRET` empty unless you want env vars to override the JSON file.\n\nExample `.env` for a local web OAuth client:\n\n```env\nGOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com\nGOOGLE_CLIENT_SECRET=your-client-secret\nGOOGLE_REDIRECT_URI=http://127.0.0.1:8787/callback\nMCP_BEARER_TOKEN=your-generated-token\nDB_PATH=./google-tasks.db\nBIND_HOST=127.0.0.1\nBIND_PORT=8787\n```\n\nIf 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.\n\n`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.\n\n## Bootstrap Google OAuth\n\nRun this once per Google account you want the server to access:\n\n```bash\ngoogle-tasks-mcp-bootstrap\n```\n\nOpen the printed URL, approve access, and paste the authorization code back into the terminal.\n\nFor multiple trusted accounts on one HTTP server, create one stored bearer token per account and bootstrap each account separately:\n\n```bash\ngoogle-tasks-mcp-create-bearer-token --account-id personal --label \"Personal account\"\ngoogle-tasks-mcp-bootstrap --account-id personal\n\ngoogle-tasks-mcp-create-bearer-token --account-id work --label \"Work account\"\ngoogle-tasks-mcp-bootstrap --account-id work\n```\n\nUse each printed bearer token only in the matching account's MCP client. The server stores only bearer-token hashes.\n\n## Start The Server\n\nHTTP mode:\n\n```bash\npython -m google_tasks_mcp --transport http\n```\n\nHealth check:\n\n```bash\ncurl http://127.0.0.1:8787/healthz\n```\n\nExpected response:\n\n```json\n{\"ok\": true}\n```\n\nStdio mode:\n\n```bash\npython -m google_tasks_mcp --transport stdio\n```\n\nConfiguration check:\n\n```bash\npython -m google_tasks_mcp --check\n```\n\n## Connect An MCP Client\n\nRemote or local HTTP:\n\n```text\nURL:  http://127.0.0.1:8787/mcp\nAuth: Bearer <MCP_BEARER_TOKEN>\n```\n\nFor a VPS, replace the URL with your HTTPS endpoint:\n\n```text\nURL:  https://your-domain.example/mcp\nAuth: Bearer <MCP_BEARER_TOKEN>\n```\n\nLocal stdio:\n\n```json\n{\n  \"command\": \"/path/to/google-tasks-mcp/.venv/bin/python\",\n  \"args\": [\"-m\", \"google_tasks_mcp\", \"--transport\", \"stdio\"]\n}\n```\n\n`MCP_BEARER_TOKEN` is not required for stdio because the MCP client launches the process locally.\n\n## Authentication Modes\n\nBearer-token mode is the default HTTP mode. `/mcp` requires `Authorization: Bearer <token>`.\n\n- `MCP_BEARER_TOKEN` routes to account `default`.\n- Tokens created with `google-tasks-mcp-create-bearer-token` can route different clients to different `account_id` values.\n- Bearer tokens are displayed once and stored only as hashes.\n\nOAuth 2.0 gateway mode is optional. Enable it when your HTTP MCP client supports OAuth authorization metadata and token refresh.\n\n- Set `MCP_OAUTH_ISSUER`, `MCP_OAUTH_CLIENT_ID`, `MCP_OAUTH_CLIENT_SECRET`, and `MCP_OAUTH_SIGNING_SECRET`.\n- Set `MCP_OAUTH_REDIRECT_URIS` to the callback URI values accepted by your MCP client.\n- `/mcp` accepts OAuth-issued access tokens and the legacy bearer token.\n- OAuth gateway refresh tokens are stored by hash and rotate on use, so clients can reconnect after server restart.\n\nLeave `MCP_OAUTH_REDIRECT_URIS` empty to keep OAuth gateway mode disabled.\n\n## Tools\n\nThe 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.\n\n| Group | Tools | Notes |\n| --- | --- | --- |\n| Tasklists | `list_tasklists`, `create_tasklist`, `get_tasklist`, `update_tasklist`, `delete_tasklist` | Tasklist delete requires `confirm: true`; non-empty lists require `force: true`. |\n| Task reads | `list_tasks`, `get_task` | Read from one tasklist. If `tasklist` is omitted, uses `DEFAULT_TASKLIST` or Google's first list. |\n| Task summaries | `today`, `overdue`, `upcoming`, `search`, `digest` | If `tasklist` is omitted, reads all tasklists and includes tasklist context. |\n| Task mutations | `clear_completed`, `add`, `complete`, `update`, `uncomplete`, `delete`, `move` | Mutate one tasklist/task at a time. `clear_completed` requires `confirm: true`. |\n\nAll `tasklist` arguments accept a tasklist ID or exact title. Task title lookup is exact after trimming whitespace and ignores case.\n\nFor `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.\n\nFor `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.\n\n## Limitations\n\nThese are Google Tasks REST API limits:\n\n- Due dates are date-only. Google drops time-of-day values on task due dates.\n- Recurring tasks cannot be created or read through the Google Tasks REST API.\n- `clear_completed` hides completed tasks; it does not permanently delete them.\n\n## Docker And VPS\n\nDocker:\n\n```bash\ndocker compose up --build\n```\n\nKeep `.env`, OAuth JSON files, and SQLite databases outside images and public bundles.\n\nVPS/systemd/Caddy templates are in `deploy/`:\n\n- [deploy/caddy/Caddyfile](./deploy/caddy/Caddyfile)\n- [deploy/systemd/google-tasks-mcp.service](./deploy/systemd/google-tasks-mcp.service)\n\nReplace every placeholder domain, path, and user before deploying.\n\n## Troubleshooting\n\nMissing bearer token:\n\n- HTTP `/mcp` requires `Authorization: Bearer <token>` unless OAuth gateway mode is handling the client.\n- Stdio mode does not use `MCP_BEARER_TOKEN`.\n\nGoogle OAuth app is in Testing mode:\n\n- Add every bootstrapped Google user as a test user.\n- Testing-mode refresh tokens can expire after 7 days.\n\nCallback URI mismatch:\n\n- `GOOGLE_REDIRECT_URI` must exactly match an Authorized redirect URI in Google Cloud.\n- For local web OAuth, use `http://127.0.0.1:8787/callback` consistently.\n\nExpired or revoked Google refresh token:\n\n- Run `google-tasks-mcp-bootstrap` again for the affected account.\n- For multi-account mode, include the same `--account-id` you used before.\n\nOAuth MCP client keeps re-authorizing:\n\n- Ensure the server is running a version with persisted MCP OAuth refresh tokens.\n- Check that `DB_PATH` points to persistent storage and survives restarts.\n- Verify `MCP_OAUTH_ISSUER` is the public HTTPS base URL with no trailing slash.\n\n## More Docs\n\n- [MCP_SERVER_GUIDE.md](./MCP_SERVER_GUIDE.md) explains hosting models, credential boundaries, and public project vs public service choices.\n- [DISTRIBUTION.md](./DISTRIBUTION.md) explains registry, bundle, and directory publishing.\n- [.env.example](./.env.example) lists every supported environment variable.\n- [google-tasks-mcp-specifications.md](./google-tasks-mcp-specifications.md) is the behavioral source of truth.\n\n## Tests\n\n```bash\npytest\n```\n",
  "bytes": 9540,
  "sha": "5c13e47e03f6686eaf7d95e6dd845abe7184484c799d90dfc5bb19253f4e8495",
  "repo_slug": "ebmurha/google-tasks-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_ebmurha_google_tasks_mcp_bae19248/readme"
}