Labsco
ebmurha logo

Google Tasks MCP

★ 1

from ebmurha

Manage Google Tasks from your AI assistant using natural language.

🔥🔥🔥✓ VerifiedAccount requiredAdvanced setup
#automation#database#cloud#devops#git

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

Use caseTransportAuth
MCP client starts the process directlystdioNo MCP_BEARER_TOKEN needed
Local HTTP serverStreamable HTTP at http://127.0.0.1:8787/mcpBearer token
VPS or other hostStreamable HTTP at https://your-domain.example/mcpBearer token or OAuth gateway

For deeper hosting and distribution guidance, see MCP_SERVER_GUIDE.md and DISTRIBUTION.md.

Bootstrap Google OAuth

Run this once per Google account you want the server to access:

google-tasks-mcp-bootstrap

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:

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

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:

python -m google_tasks_mcp --transport http

Health check:

curl http://127.0.0.1:8787/healthz

Expected response:

{"ok": true}

Stdio mode:

python -m google_tasks_mcp --transport stdio

Configuration check:

python -m google_tasks_mcp --check

Connect An MCP Client

Remote or local HTTP:

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

For a VPS, replace the URL with your HTTPS endpoint:

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

Local stdio:

{
  "command": "/path/to/google-tasks-mcp/.venv/bin/python",
  "args": ["-m", "google_tasks_mcp", "--transport", "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_TOKEN routes to account default.
  • Tokens created with google-tasks-mcp-create-bearer-token can route different clients to different account_id values.
  • 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, and MCP_OAUTH_SIGNING_SECRET.
  • Set 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.
  • OAuth gateway refresh tokens are stored by hash and rotate on use, so clients can reconnect after server restart.

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.

GroupToolsNotes
Tasklistslist_tasklists, create_tasklist, get_tasklist, update_tasklist, delete_tasklistTasklist delete requires confirm: true; non-empty lists require force: true.
Task readslist_tasks, get_taskRead from one tasklist. If tasklist is omitted, uses DEFAULT_TASKLIST or Google's first list.
Task summariestoday, overdue, upcoming, search, digestIf tasklist is omitted, reads all tasklists and includes tasklist context.
Task mutationsclear_completed, add, complete, update, uncomplete, delete, moveMutate 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.

Docker And VPS

Docker:

docker compose up --build

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.

More Docs

Tests

pytest