Google Tasks MCP

An MCP server that lets AI agents read and manage a user's Google Tasks. It uses Google's official Tasks API, OAuth 2.0 Desktop App credentials, and the MCP TypeScript SDK over stdio.

Features

• List, inspect, create, rename, and delete task lists

• List and filter tasks with API pagination

• Create, edit, complete, reopen, move, reorder, and delete tasks

• Create and move subtasks using parent and previous

• Clear completed tasks

• MCP safety annotations plus explicit confirmation for destructive operations

• OAuth refresh token stored outside the repository with owner-only permissions

Requirements

• Node.js 20 or newer

• A Google account

• A Google Cloud project with the Google Tasks API enabled

1. Configure Google Cloud

1. Open Google Cloud Console.

2. Create or select a project.

3. Enable Google Tasks API under APIs & Services → Library.

4. Configure the OAuth consent screen.

5. Under APIs & Services → Credentials, create an OAuth client ID with application type Desktop app.

6. Download the OAuth Desktop client JSON as client_secret.json and keep it protected outside this repository.

2. Install, build, and authorize

npm install
npm run build
npm run auth -- --client-secret /secure/google/client_secret.json

The auth command accepts only a Google OAuth Desktop client JSON containing the top-level installed object. It opens a browser consent flow and saves the Tasks refresh token to:

~/.config/google-tasks-mcp/token.json

Override the generated token location when needed:

GOOGLE_TOKEN_FILE=/secure/google/tasks-token.json \
npm run auth -- --client-secret /secure/google/client_secret.json

For an installed package, run:

google-tasks-mcp-auth --client-secret /secure/google/client_secret.json

The server requests the full https://www.googleapis.com/auth/tasks scope because it exposes both read and write operations. Later MCP server runs use the stored token and refresh access automatically; provide client_secret.json again only when authorizing or re-authorizing the project. Never commit either JSON file.

3. Connect an MCP host

Use the built server directly from this checkout. Replace the paths with absolute paths on your machine.

Codex (~/.codex/config.toml)

[mcp_servers.google_tasks]
command = "node"
args = ["/absolute/path/google-task-mcp/dist/index.js"]

[mcp_servers.google_tasks.env]
GOOGLE_TOKEN_FILE = "/Users/you/.config/google-tasks-mcp/token.json"

Hosts using JSON configuration

{
  "mcpServers": {
    "google_tasks": {
      "command": "node",
      "args": ["/absolute/path/google-task-mcp/dist/index.js"],
      "env": {
        "GOOGLE_TOKEN_FILE": "/Users/you/.config/google-tasks-mcp/token.json"
      }
    }
  }
}

Restart the MCP host after changing its configuration.

Available tools

Google Tasks stores only the date portion of a due timestamp. A time-of-day sent through the API is discarded. Task titles are limited to 1,024 characters and notes to 8,192 characters.

Test with MCP Inspector

npm run build
npm run inspect

The stdio protocol uses stdout exclusively. Runtime diagnostics are therefore written to stderr.

Package for distribution

Create an installable npm tarball:

npm pack

After publishing the package, a host can launch it with:

{
  "command": "npx",
  "args": ["-y", "google-tasks-mcp@0.1.0"],
  "env": {
    "GOOGLE_TOKEN_FILE": "/secure/google/tasks-token.json"
  }
}

For one user on one workstation, stdio plus a local token is the simplest and safest deployment. For multiple users or a hosted service, use MCP Streamable HTTP and implement per-user OAuth sessions and encrypted server-side token storage; do not share one refresh token among users.

References

• Google Tasks API REST reference

• Google Tasks resource fields

• Google Tasks ordering

• Google OAuth 2.0

• MCP TypeScript SDK