Google Tasks MCP

Google Tasks MCP

A Python 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 theMCP Python 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
• Python-only runtime; Node.js is not required

Requirements

• Python 3.11 or 3.12
• uv or another Python package installer
• 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 withapplication type Desktop app.
6. Download the OAuth Desktop client JSON as client_secret.json and keep itprotected outside this repository.

2. Install and authorize

Install a development checkout:

uv sync --extra dev

Authorize from a desktop that can open the browser consent flow:

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

The command accepts only a Google OAuth Desktop client JSON containing thetop-level installed object. It saves a separate Google Tasks token to:

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

Override the token location when needed:

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

The server requests the full https://www.googleapis.com/auth/tasks scopebecause it exposes read and write operations. Later MCP runs refresh accessautomatically. Never commit the OAuth client or generated token.

The same OAuth Desktop client definition may be used to authorize anotherlocal application, but each service should retain its own token and exactscope. Do not reuse a broader Google Workspace token as this service's token.

3. Connect an MCP host

Use the Python console script from the virtual environment. Replace paths withabsolute paths on the target machine.

Codex (~/.codex/config.toml)

[mcp_servers.google_tasks]
command = "/absolute/path/google-task-mcp/.venv/bin/google-tasks-mcp"

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

Hosts using JSON configuration

{
  "mcpServers": {
    "google_tasks": {
      "command": "/absolute/path/google-task-mcp/.venv/bin/google-tasks-mcp",
      "env": {
        "GOOGLE_TOKEN_FILE": "/secure/google/tasks-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-daysent through the API is discarded. Task titles are limited to 1,024 charactersand notes to 8,192 characters.

The Python implementation preserves the previous TypeScript tool names,arguments, pagination defaults, safety annotations, date normalization, andthe distinction between an omitted update field and explicit null used toclear notes or due.

Validate

Run all configured checks:

uv run ruff format --check .
uv run ruff check .
uv run mypy
uv run pytest

The regression suite dispatches all 14 tools against a fake Google Tasksclient, verifies destructive confirmation, and tests omitted-versus-null updatebehavior. A fresh MCP stdio client should discover exactly 14 tools before liveGoogle API testing.

Build and install from GitHub

Build wheel and source distributions:

uv build

Install an immutable Git commit into a dedicated virtual environment:

uv venv --python /usr/bin/python3.12 /opt/google-tasks-mcp/venv
uv pip install \
  --python /opt/google-tasks-mcp/venv/bin/python \
  "git+https://github.com/phamviet86/google-task-mcp.git@<commit>"

Launch the installed MCP server with:

/opt/google-tasks-mcp/venv/bin/google-tasks-mcp

For one user on one workstation or VPS, stdio plus a protected local token isthe simplest deployment. For multiple users or a hosted service, use MCPStreamable HTTP and implement per-user OAuth sessions and encrypted server-sidetoken storage; do not share one refresh token among users.

Migration from the TypeScript release

Version 0.2.0 replaces the Node.js implementation with Python. Before removingthe old installation:

1. Preserve the protected Google Tasks token; do not print or commit it.
2. Install this Python package into a new virtual environment.
3. Point the MCP host at the new google-tasks-mcp console script while keepingGOOGLE_TOKEN_FILE unchanged.
4. Discover exactly 14 tools and run live read/write/cleanup tests.
5. Remove the old Node checkout only after the Python server is verified.

References

• Google Tasks API REST reference
• Google Tasks resource fields
• Google Tasks ordering
• Google OAuth 2.0
• MCP Python SDK