google-tasks-mcp-server

An MCP server (stdio) for operating Google Tasks. It provides CRUD for task lists and tasks, completion toggling, reordering/moving, and batch-hiding of completed tasks.

Google's official Workspace MCP servers (Gmail / Calendar / Drive, etc.) do not include Tasks, so I built this to fill that gap.

Design principles

• Credentials are passed via a file. You specify the path to the client_secret_*.json downloaded from GCP in an environment variable, so you do not have to write the client secret in plain text in the MCPconfiguration file.

• First-time authentication is done in a separate CLI. Because the MCP server occupies stdout with JSON-RPC, mixing in browser launches or logs would break the protocol. Pulling authentication into npm run auth avoids that conflict and makes failures easier to isolate.

• Tasks-Only scope. It only requests https://www.googleapis.com/auth/tasks.

• Updates use patch. update would erase unspecified fields, so partial updates always use patch.

Related MCP server: Mini Task MCP Server

Setup

1. Prepare GCP

1. Enable Google Tasks API in APIs & Services → Library

2. Create an OAuth 2.0 Clientes ID in Credentials, and use Desktop app as the application type.

   • Because a Desktop app can use any loopback port as its configured redirect target, you do not need to register a redirect URI.

3. Downloade the JSON (client_secreat_xxx.json).

4. If the OAuth consent screen is in “Testing” status, add your own Google account as a test user.

2. Build

npm install
npm run build

3. First-time authentication

Authenticate by specifying the path to the client_secret_*.json. A browser will open, so approve it.

GOOGLE_TASKS_CLIENT_SECRET_PATH=~/path/to/client_secret_xxx.json npm run auth

The token are saved to ~/.config/google-tasks-mcp-server/token.json with permissions 0600. From then on, the refresh token refreshes it automatically, so this step is required only the first time.

4. Register with the MCP client

For Claude Code:

claude mcp add google-tasks \
  -e GOOGLE_TASKS_CLIENT_SECRET_PATH=$HOME/path/to/client_secret_xxx.json \
  -- node /absolute/path/to/google-tasks-mcp-server/dist/index.js

If you write it directly in .mcp.json:

{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/google-tasks-mcp-server/dist/index.js"],
      "env": {
        "GOOGLE_TASKS_CLIENT_SECRET_PATH": "/absolute/path/to/client_secret_xxx.json"
      }
    }
  }
}

Environment variables

Tools

When omitted, the tasklist defaults to @not (the default task list).

Tasks lists

Tasks

Notes on usage

• No time is stored in the due value. due is passed as RFC 3339, but Google Tasks retains only the date portion.

• Retrieving completed tasks requires showHidden. showCompleted: true alone does not return tasks completed by other clients, so this server automatically adds showHidden when showCompleted: true is used.

• clear-completed-tasks is not a deletion. It only hides them, and they can be retrieved with showHidden: true.

• Due-date filters are corrected to be inclusive of the specified date. Google Tasks API’s dueMax is exclusive on date basis; even if you pass the day at 23:59:59, zero tasks due that day are returned (you need to pass the next day at 0:00). Because that is counterintuitive, this server normalizes dueMin and dueMax to date boundaries so both filters include the specified date.

Development

npm run typecheck   # 型チェックのみ
npm run build       # dist/ に出力
npm run auth        # 初回認証

License

MIT

Setup script

After completing the GCP console steps (enabling Google Tasks API, creating an OAuth 2.0 desktop app client, and downloadeing the JSON), you can run everything else at once.

./scripts/setup.sh

It automatically searches ~/Downloads for client_secret*.json , verifies its type, places it in ~/.config/google-tasks-mcp-server/ with permission 600, then runs to build, authenticates the first time, and registers the MCP server. If the file is elsewhere, pass its path.

./scripts/setup.sh /path/to/client_secret.json