{
  "markdown": "# google-tasks-mcp-server\n\n[![npm](https://img.shields.io/npm/v/@girmmy/google-tasks-mcp-server)](https://www.npmjs.com/package/@girmmy/google-tasks-mcp-server)\n[![CI](https://github.com/girmmy/google-tasks-mcp-server/actions/workflows/ci.yml/badge.svg)](https://github.com/girmmy/google-tasks-mcp-server/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)\n\nAn [MCP](https://modelcontextprotocol.io) server for [Google Tasks](https://tasks.google.com). Gives any MCP client (Claude Desktop, Claude Code, Codex, Cursor, etc.) full read/write access to your task lists and tasks: list, create, update, complete, delete, and move them, with real due dates.\n\nThere's no official Google Tasks MCP server, so this covers that. Full CRUD, OAuth installed-app auth flow (your credentials never leave your machine), TypeScript throughout.\n\n## Tools\n\n**Task lists**\n- `google_tasks_list_tasklists` list all task lists\n- `google_tasks_get_tasklist` get one task list\n- `google_tasks_create_tasklist` create a new task list\n- `google_tasks_update_tasklist` rename a task list\n- `google_tasks_delete_tasklist` delete a task list and all its tasks\n\n**Tasks**\n- `google_tasks_list_tasks` list tasks in a list, with due-date/updated filters and pagination\n- `google_tasks_get_task` get one task\n- `google_tasks_create_task` create a task (optionally as a subtask, optionally positioned)\n- `google_tasks_update_task` update title/notes/due date/status\n- `google_tasks_complete_task` / `google_tasks_reopen_task` mark done / not done\n- `google_tasks_delete_task` delete a task\n- `google_tasks_move_task` reorder, re-parent, or move a task to a different list\n- `google_tasks_clear_completed_tasks` clear all completed tasks from a list\n\nEvery tool supports `response_format: \"markdown\" | \"json\"`.\n\n## Quick start\n\nFrom npm:\n\n```bash\nnpm install -g @girmmy/google-tasks-mcp-server\n```\n\nOr don't install it at all and let your MCP client run it via `npx` (see [step 4](#4-run-it)).\n\nOr from source:\n\n```bash\ngit clone https://github.com/girmmy/google-tasks-mcp-server.git\ncd google-tasks-mcp-server\nnpm install\nnpm run build\n```\n\nEither way, follow Setup below to create your own Google OAuth credentials and authorize. There's no shared or hosted version of this, it talks directly to your own Google account.\n\n## Setup\n\n### 1. Create a Google Cloud OAuth client\n\nEach user needs their own OAuth client. It's not something that can be shared, since anyone using your client secret could impersonate your app (though they'd still need each individual user's own consent).\n\n1. Go to the [Google Cloud Console](https://console.cloud.google.com/), create (or pick) a project.\n2. APIs & Services → Library → enable the Google Tasks API.\n3. APIs & Services → OAuth consent screen (Google now calls this \"Google Auth Platform\"):\n   - User type: External is fine for personal use.\n   - Fill in app name and your email for support/contact.\n   - Under Audience → Test users, add your own Google account. While the app is in \"Testing\" status only listed test users can authorize it, which is fine for running this yourself.\n4. Clients → Create Client → Application type Desktop app. Create it.\n5. Grab the client ID and client secret, either via \"Download JSON\" right after creation or from the client's detail page later. Google's console won't show a secret's plaintext again once you navigate away, only download or regenerate it, so if you lose it just add a new secret instead of hunting for the old one.\n6. Save that file. By default this server looks for it at:\n   `~/.config/google-tasks-mcp-server/client_secret.json`\n   (override the path with the `GOOGLE_TASKS_CLIENT_SECRET` env var, useful if you'd rather keep it inside the project directory, e.g. `./credentials/client_secret.json`. `credentials/` is already gitignored.)\n\nThe file should look like:\n\n```json\n{\n  \"installed\": {\n    \"client_id\": \"YOUR_CLIENT_ID.apps.googleusercontent.com\",\n    \"client_secret\": \"YOUR_CLIENT_SECRET\",\n    \"auth_uri\": \"https://accounts.google.com/o/oauth2/auth\",\n    \"token_uri\": \"https://oauth2.googleapis.com/token\",\n    \"redirect_uris\": [\"http://localhost\"]\n  }\n}\n```\n\n### 2. Install\n\nFrom npm (nothing to build):\n\n```bash\nnpm install -g @girmmy/google-tasks-mcp-server\n```\n\nFrom source:\n\n```bash\nnpm install\nnpm run build\n```\n\n### 3. Authorize (one-time)\n\nIf you installed from npm:\n\n```bash\ngoogle-tasks-mcp-auth\n# or without installing anything:\nnpx -y -p @girmmy/google-tasks-mcp-server google-tasks-mcp-auth\n```\n\nFrom source:\n\n```bash\nnpm run auth\n# or, if your client secret lives at a custom path:\nGOOGLE_TASKS_CLIENT_SECRET=./credentials/client_secret.json npm run auth\n```\n\nThis prints a Google consent URL and tries to open it in your default browser. Sign in, grant access, and it redirects back to a short-lived local server on `http://localhost:53682`. The token gets cached to `~/.config/google-tasks-mcp-server/token.json` (override with `GOOGLE_TASKS_TOKEN_PATH`) and refreshed automatically from then on, so you shouldn't need to run this again unless you revoke access.\n\nRun this on the same machine and in the same regular terminal you'll actually use day to day. See Troubleshooting below if you're running it from a container, VM, or sandboxed shell where `localhost` doesn't map back to your browser.\n\n### 4. Run it\n\n```bash\nnpm start\n```\n\nOr wire it into an MCP client. For Claude Desktop / Claude Code, add to your MCP config (usually `~/Library/Application Support/Claude/claude_desktop_config.json` on macOS).\n\nUsing npm, with your client secret at the default `~/.config/...` path, this is the whole config:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-tasks\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@girmmy/google-tasks-mcp-server\"]\n    }\n  }\n}\n```\n\nOr pointing at a source checkout:\n\n```json\n{\n  \"mcpServers\": {\n    \"google-tasks\": {\n      \"command\": \"node\",\n      \"args\": [\"/absolute/path/to/google-tasks-mcp-server/dist/index.js\"],\n      \"env\": {\n        \"GOOGLE_TASKS_CLIENT_SECRET\": \"/absolute/path/to/google-tasks-mcp-server/credentials/client_secret.json\"\n      }\n    }\n  }\n}\n```\n\nOmit the `env` block if you saved your client secret at the default `~/.config/...` path. Fully quit and reopen your MCP client afterward.\n\n### Codex\n\nCodex uses TOML rather than JSON. Add this to `~/.codex/config.toml`:\n\n```toml\n[mcp_servers.google-tasks]\ncommand = \"npx\"\nargs = [\"-y\", \"@girmmy/google-tasks-mcp-server\"]\nstartup_timeout_sec = 60\n```\n\nOr let the CLI write it for you:\n\n```bash\ncodex mcp add google-tasks -- npx -y @girmmy/google-tasks-mcp-server\n```\n\nRaise `startup_timeout_sec` if the first launch times out. A cold `npx` downloads the\npackage before the server can answer `initialize`, and Codex's default allowance is short\nenough that this sometimes trips on the first run only.\n\nIf your client secret isn't at the default path, add:\n\n```toml\n[mcp_servers.google-tasks.env]\nGOOGLE_TASKS_CLIENT_SECRET = \"/absolute/path/to/client_secret.json\"\n```\n\nCheck it registered with `codex mcp list`. Authorization is the same one-time\n`google-tasks-mcp-auth` step as everywhere else — run it in a normal terminal, not inside\nCodex, since it needs to open a browser and catch a loopback redirect.\n\n## Environment variables\n\n| Variable | Default | Purpose |\n|---|---|---|\n| `GOOGLE_TASKS_CLIENT_SECRET` | `~/.config/google-tasks-mcp-server/client_secret.json` | Path to the downloaded OAuth client JSON |\n| `GOOGLE_TASKS_TOKEN_PATH` | `~/.config/google-tasks-mcp-server/token.json` | Path where the cached OAuth token is stored |\n| `GOOGLE_TASKS_OAUTH_PORT` | `53682` | Loopback port used only during `npm run auth` |\n\n## Security notes\n\n- The client secret and cached token are plain files on disk (mode `0600` for the token). Never commit them (`.gitignore` already excludes `client_secret*.json`, `token.json`, `credentials/`).\n- The server requests the full `https://www.googleapis.com/auth/tasks` scope (read/write). For read-only access, edit `TASKS_SCOPE` in `src/constants.ts` to `.../auth/tasks.readonly` before running `npm run auth`. Write tools will then fail with a 403 from Google, which is expected.\n- Tool annotations mark deletion/clear operations as `destructiveHint: true` so MCP clients can warn or gate on them.\n- Nothing here talks to any server but Google's own APIs and, during `npm run auth`, a local loopback listener. No third-party backend involved.\n\n## Troubleshooting\n\n**`npm run auth` opens a URL, I click Allow, and it just hangs.**\nThe process running `npm run auth` isn't on the same machine/network as the browser you're clicking Allow in. Common if you're running the server inside a container, remote dev environment, or sandboxed shell that isolates `localhost`. Fix: run `npm run auth` directly in a normal local terminal on the machine whose browser you're using.\n\n**`Error [TransformError] ... You installed esbuild for another platform`**\nYour `node_modules` was installed on a different OS/architecture than you're running on now, e.g. copied from a Docker container or a different machine. Fix: `rm -rf node_modules package-lock.json && npm install`.\n\n**`Authorization failed: invalid_client`**\nYour `client_secret.json` has the wrong client secret in it, usually from copy-pasting it by hand instead of downloading it directly. Go back to Google Cloud Console, add a fresh client secret, download or copy it directly, and update your `client_secret.json`.\n\n**Server exits immediately with \"No cached Google Tasks token found\"**\nYou haven't authorized yet, or the flow didn't finish. Run `google-tasks-mcp-auth` (npm install) or `npm run auth` (source checkout) before starting the server.\n\n## Development\n\n```bash\nnpm run dev     # run directly from TypeScript with auto-reload\nnpm run build   # type-check and compile to dist/\n```\n\nTest with the [MCP Inspector](https://github.com/modelcontextprotocol/inspector):\n\n```bash\nnpx @modelcontextprotocol/inspector node dist/index.js\n```\n\n## Contributing\n\nIssues and PRs welcome. This covers the full Tasks API surface but hasn't been tested across every edge case, so if you hit a bug or want a feature, open an issue.\n\n## License\n\nMIT, see [LICENSE](LICENSE).\n",
  "bytes": 10203,
  "sha": "fe733e1a11ebab880a6cc3618abf025f6f59f32ca43610691c507bfbc20c8b3e",
  "repo_slug": "girmmy/google-tasks-mcp-server",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_girmmy_google_tasks_f7f17f26/readme"
}