@alvincrave/gtasks-mcp

Google Tasks MCP Server

A Model Context Protocol (MCP) server for Google Tasks. Manage task lists and tasks through natural language in Claude Desktop and other MCP clients.

Forked from zcaceres/gtasks-mcp with stronger auth options, multi-list support, pagination, and hierarchy tools.

Registry name: io.github.alvinjchoi/gtasks-mcp
npm: @alvincrave/gtasks-mcp

Features

• List and search tasks (optionally scoped to one task list)
• Paginate through all tasks (no silent 100-task cap)
• Create, update, delete, and clear completed tasks
• Discover task lists (list_task_lists)
• View parent/child hierarchy (list_with_tree)
• Reorder, nest, or move tasks across lists (move)
• OAuth2 auth via env vars, credential files, or interactive auth
• Docker support

Installation

Recommended (Claude Desktop / any MCP client) — runs the latest published npm package:

npx -y @alvincrave/gtasks-mcp

Or install globally:

npm install -g @alvincrave/gtasks-mcp

From source

git clone https://github.com/alvinjchoi/gtasks-mcp.git
cd gtasks-mcp
npm install
npm run build

Setup

Option A — Environment variables (Claude Desktop)

• Create a Google Cloud project and enable the Google Tasks API.
• Create OAuth 2.0 Desktop credentials and obtain a refresh token (OAuth Playground with scope https://www.googleapis.com/auth/tasks works).
• Configure Claude Desktop (~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "gtasks": {
      "command": "npx",
      "args": ["-y", "@alvincrave/gtasks-mcp"],
      "env": {
        "GOOGLE_CLIENT_ID": "your_client_id_here",
        "GOOGLE_CLIENT_SECRET": "your_client_secret_here",
        "GOOGLE_REFRESH_TOKEN": "your_refresh_token_here"
      }
    }
  }
}

Option B — Credential files (local / shared with other Google MCP servers)

• Download your OAuth client JSON (gcp-oauth.keys.json).
• Authenticate once:

export GTASKS_CREDENTIALS_PATH=/path/to/gcp-oauth.keys.json
export GTASKS_TOKEN_PATH=/path/to/.gtasks-server-credentials.json
node dist/index.js auth

• Run the server with the same env vars set (or place gcp-oauth.keys.json in the project root and use the defaults).

Aliases also accepted:

Purpose	Preferred	Alias
OAuth client keys	GTASKS_CREDENTIALS_PATH	GOOGLE_OAUTH_KEYS_PATH
Saved tokens	GTASKS_TOKEN_PATH	GOOGLE_TASKS_CREDENTIALS_PATH

Option C — Home config file

Create ~/.gtasks-credentials.json:

{
  "clientId": "your_client_id",
  "clientSecret": "your_client_secret",
  "refreshToken": "your_refresh_token"
}

Tools

Tool	Description
search	Search tasks by title/notes. Optional taskListId.
list	List tasks (all lists, or one via taskListId). Fully paginated.
list_task_lists	List task list names and IDs.
list_with_tree	Tree view for one list (parent/child, position order).
move	Reorder, nest/un-nest, or move across lists.
create	Create a task (title required; optional notes/due/taskListId).
update	Patch a task (only provided fields change).
delete	Delete a task.
clear	Clear completed tasks from a list.

Usage examples

show my task lists
list tasks in list <id>
search for tasks containing "meeting"
create a task named "Prepare presentation" due 2026-07-20
show the task tree for list <id>
move task <id> under parent <parentId>
mark task <id> completed

Docker

docker build -t gtasks-mcp .
docker run -i \
  -e GOOGLE_CLIENT_ID=your_client_id \
  -e GOOGLE_CLIENT_SECRET=your_client_secret \
  -e GOOGLE_REFRESH_TOKEN=your_refresh_token \
  gtasks-mcp

Development

npm install
npm run build
npm start

Auth check / interactive login:

npm run build
node dist/index.js auth

Security Notes

• Treat refresh tokens like passwords
• Prefer env vars or ignored credential files — never commit them
• Rotate credentials if they leak

Contributors

• ArtyMcLabin — pagination, taskListId filtering, list_task_lists, list_with_tree, move, and file-based auth (#1)
• zcaceres — original Google Tasks MCP server
• alvinjchoi — fork maintenance, Smithery/npm packaging

See CONTRIBUTORS.md.

License

MIT