google-tasks-mcp

An MCP server for Google Tasks. It uses the official Google Tasks API to read, create, edit, complete, reorder and delete your tasks.

The tool surface mirrors what a person can do in the Google Tasks app, which keeps it plain and adaptable to however you use Tasks. It works with any MCP client, including Claude Code and Claude Desktop, and anything else that speaks MCP over stdio.

Status: read and write tools are implemented and in daily use.

Setup

1. Google Cloud (one time, about 15 minutes)

You bring your own OAuth client. Your tasks and tokens never leave your machine.

1. Create a project at console.cloud.google.com.

2. Enable the Google Tasks API (APIs & Services, then Library, then "Google Tasks API", then Enable).

3. Configure the OAuth consent screen: user type External, add the scope https://www.googleapis.com/auth/tasks, and add yourself as a test user.

4. Set the publishing status to "In production." You will see an "unverified app" warning once when you authorize, which you can click through. If you leave the status at Testing, Google revokes your refresh token every 7 days and the server will appear to break for no reason.

5. Credentials, then Create credentials, then OAuth client ID, with application type Desktop app.

6. Download the JSON and save it as:

   • Windows: %APPDATA%\google-tasks-mcp\gcp-oauth.keys.json

   • macOS/Linux: ~/.config/google-tasks-mcp/gcp-oauth.keys.json

   Or put it anywhere and set GTASKS_CREDENTIALS_PATH.

2. Install and authorize

npm install
npm run auth

That opens your browser once, completes a loopback and PKCE flow, and writes a refresh token to %APPDATA%\google-tasks-mcp\tokens.json (or ~/.config/google-tasks-mcp/tokens.json). The token is never stored in this repo and never logged.

3. Verify

npm run smoke

Builds the server, launches it over stdio as a real MCP client would, and calls every read tool against your account. It never writes.

4. Connect a client

For Claude Code:

claude mcp add google-tasks -- node /absolute/path/to/google-tasks-mcp/dist/index.js serve

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/google-tasks-mcp/dist/index.js", "serve"]
    }
  }
}

Use an absolute path to node if a bare node is not on your client's PATH.

Related MCP server: Google-Tasks-Local-MCP-Server

Tools

Reading

Writing

Set GTASKS_READONLY=1 to run with the read-only Google scope. The write tools are then not registered at all.

list_id accepts a real id, the list title, or the alias shown by list_task_lists, so a handle copied from earlier output resolves without another lookup.

Environment variables

The two path overrides let one install serve multiple Google accounts.

What the API allows

These are properties of the Google Tasks API itself, and they shape how the server behaves.

Repeating tasks are not available. The API has no recurrence field. Repeating tasks created in the Google Tasks app work normally and roll forward on Google's side, but through the API they appear as ordinary one-off tasks, and a repeat cannot be set. This affects every third-party Google Tasks integration equally.

Because repeats are invisible, deleting one instance through the API can delete the entire series. delete_task guards against this by refusing when another task in the same list has the exact same title, which is the only available hint. Pass force: true to override.

Due dates are calendar dates. The API discards the time portion, so a due time can be neither set nor read.

Other constraints handled internally: results are paginated (maxResults defaults to 20 and caps at 100), updates use patch rather than update so untouched fields survive, and completed tasks become hidden, so reading them needs include set to completed or all. There is no search endpoint, so search_tasks filters client-side.

License

MIT