Google Tasks

A Model Context Protocol (MCP) server for Google Tasks. Lets AI assistants list, create, update, delete, and complete tasks via the Google Tasks API.

Why this exists

I prefer Google Tasks over Google Calendar for managing todos. The excellent google-calendar-mcp project only covers the Calendar API, so I built this quick-and-dirty companion to fill the gap. If you'd like to fold Tasks support into that project, PRs are welcome there.

Quick Start

1. Enable the Google Tasks API

1. Go to the Google Cloud Console
2. Create a new project or select an existing one
3. Enable the Google Tasks API (make sure the correct project is selected in the top bar)
4. Create OAuth 2.0 credentials:
   • Go to Credentials
   • Click Create Credentials > OAuth client ID
   • Choose Desktop app as the application type
   • Download the JSON file (you'll reference its path below)
5. Configure the OAuth consent screen:
   • Add your email as a Test User
   • Note: test-mode tokens expire after 7 days (see Limitations)

2. Install

Add to your MCP client config (Cursor, Claude Desktop, etc.):

{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": ["-y", "@scottie-will/google-tasks-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}

3. Authenticate

Option A — CLI (recommended for first run):

GOOGLE_OAUTH_CREDENTIALS=/path/to/gcp-oauth.keys.json npx @scottie-will/google-tasks-mcp auth

Complete the OAuth flow in your browser, then restart your MCP client.

Option B — Via the agent:

Ask your AI assistant to "authenticate with Google Tasks". The authenticate tool will return a URL to visit in your browser. After completing sign-in, tell the agent to verify authentication.

Available Tools

Tool	Description
authenticate	Start or verify Google OAuth authentication
list-task-lists	List all task lists for the authenticated user
list-tasks	List tasks with optional date filtering and completion status
get-task	Get a specific task by ID
create-task	Create a new task (supports subtasks via parent)
update-task	Update an existing task (partial updates supported)
delete-task	Permanently delete a task
complete-task	Mark a task as completed

Environment Variables

Variable	Required	Description
GOOGLE_OAUTH_CREDENTIALS	Yes	Path to your OAuth credentials JSON file
GOOGLE_TASKS_MCP_TOKEN_PATH	No	Custom path for token storage (default: ~/.config/google-tasks-mcp/tokens.json)

Limitations

• Dates only, no times. The Google Tasks API stores due dates only — any time component in the due field is silently discarded. Workaround: prefix the task title with a 24-hour time (e.g. "0900 Team standup") for manual time-based ordering.
• Position-based ordering only. Tasks are returned in position order (the drag-order from the Google Tasks UI). There is no server-side sort by due date — sort client-side after fetching.
• No pagination. Each list call returns at most 100 items. Large task lists may be truncated.
• Test-mode token expiry. While your GCP app is in test mode, OAuth tokens expire after 7 days. To avoid this, publish your app to production (no verification needed for personal use — Google will show an "unverified app" warning).
• Single account. Only one Google account is supported at a time.

For full API details, see the Google Tasks API reference.

Agent Setup Instructions

This server includes built-in instructions metadata (via the MCP protocol) that teaches agents how to use it effectively — covering the auth flow, date-only behavior, sorting quirks, @default task list conventions, and destructive-operation guardrails. Compatible MCP clients (Cursor, Claude Desktop, etc.) surface these instructions automatically.

If your client supports serverUseInstructions in the MCP config, you can also add custom hints. See incident.io's MCP for an example of thorough server instructions.

GCP API Access Required

This server requires:

• API: Google Tasks API (tasks.googleapis.com)
• OAuth scope: https://www.googleapis.com/auth/tasks (full read/write access to tasks)
• Credential type: OAuth 2.0 Client ID — Desktop app type

No API key or service account is needed. The OAuth flow runs locally and tokens are stored on your machine at ~/.config/google-tasks-mcp/tokens.json.

Credits

• Inspired by and modeled after google-calendar-mcp by @nspady. That project covers the Google Calendar API with multi-account support, recurring events, and much more. If you'd like to add Tasks support there, open a PR — it would be a natural fit.
• Built with the Model Context Protocol SDK.

License

MIT