gtasks-mcp

A Model Context Protocol server for Google Tasks — list, search, create, update, delete, and clear tasks from Claude (or any MCP-compatible client).

Adapted from zcaceres/gtasks-mcp (MIT), rebuilt on plain Node/TypeScript instead of Bun, with credentials moved out of the repo entirely (see Security below) and a full test suite.

Setup

1. Create a Google Cloud OAuth client

1. Go to the Google Cloud Console, create a project (or reuse one).
2. Enable the Google Tasks API (APIs & Services → Library).
3. Configure the OAuth consent screen (External is fine for personal use — you'll be the only test user).
4. Create credentials → OAuth client ID → Application type Desktop app.
5. Download the JSON file.

2. Install the OAuth client file

mkdir -p ~/.gtasks-mcp
mv ~/Downloads/client_secret_*.json ~/.gtasks-mcp/oauth-keys.json

On Windows: %USERPROFILE%\.gtasks-mcp\oauth-keys.json.

3. Build and authenticate

npm install
npm run build
npm run auth

This opens a browser window for the Google consent flow. On success, a credentials.json (your refresh/access token) is written next to oauth-keys.json in ~/.gtasks-mcp/.

4. Register the server with Claude Code

claude mcp add gtasks -- node /absolute/path/to/gtasks-mcp/dist/index.js

Tools exposed

Tool	Description
list	List tasks (all lists, or one via taskListId)
search	Search tasks by title/notes
list-tasklists	List all task lists
create	Create a task (title required)
update	Update a task (id required)
delete	Delete a task (id required)
clear	Clear completed tasks from a list

Security

• Credentials never live inside this repo. oauth-keys.json (your Google Cloud OAuth client) and credentials.json (your personal access/refresh token, generated by npm run auth) are both stored under ~/.gtasks-mcp/ — the OS user-config area, not the project directory. There is no gitignored file inside the repo to accidentally git add -f; the secrets aren't reachable from the repo's working tree at all. See src/config.ts for the exact paths.
• credentials.json is equivalent to a password to your Google Tasks — anyone with that file can read/write your tasks. Treat it accordingly (don't email it, don't paste it in a chat, don't back it up somewhere shared).
• Dependencies: only @google-cloud/local-auth, googleapis, and @modelcontextprotocol/sdk — all official (Google / Anthropic). No telemetry, no third-party network calls; every request goes to Google's own APIs.
• Known, accepted transitive vulnerabilities (npm audit, checked 2026-08-25): moderate-severity issues in esbuild/vite (dev-only tooling, not part of the runtime) and uuid (via gaxios/googleapis, no untrusted-buffer input path in this server's actual usage). Both require a breaking major-version bump upstream to clear; revisit at the next periodic dependency audit rather than force an untested upgrade.

Development

npm test        # vitest
npm run lint     # eslint (narrow scope — see eslint.config.js)
npm run typecheck
npm run build