# Google Tasks MCP [Health: Active]

**Category:** 🏢 Workplace & Productivity  
**Repository:** https://github.com/A1-x-Tech/mcp-google-tasks  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1025  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/google-tasks-mcp

## Description
MCP server for the Google Tasks API: task lists, subtasks, due dates, complete and move tasks.

## Tools
Capabilities this server exposes over MCP:

- **auth_status** — Shows whether this server is connected to Google: token presence and source (env variables or a stored in-chat login), expiry, the Google account email, granted vs missing OAuth scopes, where the credentials file lives and where the OAuth client comes from. Makes no network calls and never returns the token itself. Call it first when other tools report the server is not connected.
- **setup_instructions** — Step-by-step checklist for connecting this server to Google: creating a Google Cloud project and a Desktop-app OAuth client, publishing the consent screen (mandatory — Testing-mode refresh tokens die after 7 days), downloading the client JSON and handing its PATH to set_client. Works without any credentials; the checklist shortens to 'enable the API + log in' when an OAuth client is already configured (one client serves the whole mcp-google-* line). Never asks the user to paste secrets into the chat.
- **set_client** — Saves the OAuth client credentials from the JSON file downloaded from Google Cloud Console ('Download JSON' on a Desktop-app client). Pass the file PATH — the secret must never be pasted into the chat. The client is stored once in the shared ~/.config/mcp-google-auth/client.json (owner-only) and reused by every mcp-google-* server; tokens stay per-server. After this, call start_login.
- **start_login** — First step of connecting from the chat, without editing config files or restarting the client. Returns authorizeUrl — show it to the user as a clickable link and ask them to open it in the browser ON THIS MACHINE, pick the Google account and approve access. A one-shot listener on 127.0.0.1 catches Google's redirect; the code is exchanged locally and never passes through the chat. Does not open the browser itself. The attempt lives 10 minutes; when the browser shows the success page, call finish_login.
- **finish_login** — Second step: waits up to 20 s for the browser consent to finish, saves the tokens to an owner-only file and verifies the login with a read-only identity call, returning the account email and the granted scopes. After success every tool works immediately — no client restart. If the user granted only part of the requested permissions, the login is still saved and missingScopes lists what will not work. Logging in under a different Google account replaces the previous login (its refresh token is revoked best-effort) and the response carries previousAccountEmail so the change never goes unnoticed.
- **logout** — Revokes the stored token at Google (oauth2.googleapis.com/revoke) and deletes the local credentials file. Tokens supplied via env variables are NOT touched — remove them from the MCP client config manually; envTokenStillSet in the response says whether any are still in effect.
- **list_tasklists** — Lists the user's task lists: id, title, updated (RFC3339). Every task lives in exactly one list, so this is the entry point — task tools need a tasklist_id from here (or the "@default" alias for the default list). Paginate with page_token from nextPageToken; page_size caps a page at 1000 and the API's default is already 1000, so one call usually returns everything. The API has no search or ordering — filter client-side.
- **get_tasklist** — Fetches one task list by id: id, title, updated, selfLink. Accepts "@default" for the user's default list — useful to resolve its real id. The list resource carries only metadata; the tasks themselves come from list_tasks.
- **create_tasklist** — Creates a new task list and returns it (id, title, updated). The API accepts only a title — there are no other list-level settings. The returned id is the tasklist_id every task tool needs. Google caps the number of lists per account; a quota failure surfaces as an HTTP error, not silence.
- **update_tasklist** — Renames a task list (PATCH — the title is the only field the API lets you change). Tasks, their order and their completion state are untouched. Returns the updated list resource.
- **delete_tasklist** — Deletes a task list AND every task in it, permanently — there is no undo and no trash. The user's default task list cannot be deleted (the API rejects it). To empty a list but keep it, use clear_completed_tasks or delete tasks one by one instead. Returns {deleted:true} with the tasklist_id echoed.
- **list_tasks** — Lists tasks in one list: id, title, notes, status (needsAction|completed), due (date only — the API never stores a time of day), completed timestamp, parent (subtask's parent id), position (opaque sort key within siblings — sort by it client-side; change it only via move_task), updated, deleted/hidden flags, webViewLink. IMPORTANT: tasks completed in Google's own apps are also flagged hidden — pass show_completed=true AND show_hidden=true to reliably see all completed tasks. For incremental sync poll with updated_min plus show_deleted=true and show_hidden=true, so deletions and clears are not missed (the API has no push notifications). due_min/due_max bound the due date; completed_min/completed_max the completion time. Paginate with page_token; page_size caps at 100 (API default 20). Filtering by due/completed dates implies those fields exist — tasks without a due date never match due bounds.
- **get_task** — Fetches one task by id: title, notes, status, due (date only), completed timestamp, parent, position, updated, deleted/hidden flags, links and webViewLink. Also the safe way to verify state after an ambiguous write failure — writes are never retried automatically.
- **create_task** — Creates a task in a list and returns it (id, title, position, webViewLink, ...). due accepts YYYY-MM-DD or an RFC3339 timestamp, but Google Tasks stores only the DATE — any time of day is discarded and never returned. notes is plain text (max 8192 chars); title max 1024 chars. Hierarchy and order are set at creation via parent (the id of an existing task in the same list — the new task becomes its subtask; Google Tasks supports one level of nesting reliably) and previous (the sibling to insert after; omit both to land at the top of the list). New tasks start as needsAction — use complete_task to complete. Recurrence cannot be created or read through the API.
- **update_task** — Changes a task's title, notes and/or due date (PATCH — only the provided fields change, at least one is required). clear_due=true / clear_notes=true erase the field entirely (you cannot clear by sending an empty string a Google API would keep). This tool does NOT change completion status (use complete_task / reopen_task), and cannot re-parent or reorder (use move_task) — parent and position are read-only in the task resource. Returns the updated task.
- **move_task** — Moves a task: under a parent (subtask), after a sibling (previous), and/or into another list (destination_tasklist). Omitting parent puts it at the top level; omitting previous puts it first among its siblings — so calling with neither moves the task to the very top of its list. This is the ONLY way to change hierarchy or order (parent/position are read-only fields; positions are opaque strings maintained by the API). Constraints: parent and previous must be in the task's (destination) list; assigned tasks and recurrent tasks cannot be moved between lists. Returns the task with its new position.
- **delete_task** — Deletes a task permanently — this is NOT the same as completing it. To mark work done (reversibly), use complete_task instead. A deleted task disappears from default listings immediately; for a while it remains visible to list_tasks with show_deleted=true (deleted:true) so sync clients can observe the deletion, then it is gone for good. Deleting a parent task also deletes its subtasks. Returns {deleted:true} with the ids echoed.
- **complete_task** — Marks a task completed (status=completed; the API stamps the completed timestamp). This is REVERSIBLE — reopen_task undoes it — and is the right call for "done", unlike delete_task which erases the task. The API call touches only the addressed task: completing a parent does NOT cascade to its subtasks — complete them individually if the whole tree is done. A completed task stays listed until cleared: list_tasks still returns it with show_completed=true (+ show_hidden=true after a clear). Returns the updated task with status and completed.
- **reopen_task** — Reverts a completed task to needsAction and clears its completed timestamp — the undo for complete_task. Works on hidden tasks too (tasks cleared with clear_completed_tasks): reopening un-hides them. Cannot resurrect a deleted task — deletion is permanent. Returns the updated task.
- **clear_completed_tasks** — Clears ALL completed tasks from one list in a single call: they are flagged hidden and vanish from default listings (the Google Tasks UI does this as "Delete all completed"). The tasks are not deleted — list_tasks with show_completed=true and show_hidden=true still returns them, and reopen_task can restore any of them individually — but there is no single call to un-clear a whole list, so treat it as destructive. Open (needsAction) tasks are untouched. Returns {cleared:true} with the tasklist_id echoed.
- **raw_request** — Escape hatch to call any Google Tasks API v1 path directly, for requests the typed tools don't cover — e.g. a full-resource PUT ("tasks/v1/lists/<listId>/tasks/<taskId>", method PUT, body with the complete task), or a query combination the typed filters don't expose. The path is relative to https://tasks.googleapis.com and may carry a query string (e.g. "tasks/v1/lists/<listId>/tasks?showDeleted=true"). The Bearer token is added automatically; the method defaults to GET. PATCH/PUT/POST/DELETE hit live data with no confirmation — prefer the typed tools when one fits.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "google-tasks-mcp": {
    "command": "npx",
    "args": ["-y","mcp-google-tasks@latest"],
    "env": {
      "GOOGLE_TASKS_CLIENT_ID": "",
      "GOOGLE_TASKS_CLIENT_SECRET": "",
      "GOOGLE_TASKS_REFRESH_TOKEN": ""
    }
  }
}
```

**Requires environment variables:** `GOOGLE_TASKS_CLIENT_ID`, `GOOGLE_TASKS_CLIENT_SECRET`, `GOOGLE_TASKS_REFRESH_TOKEN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Google Tasks MCP does

Google Tasks MCP exposes Google Tasks through the Model Context Protocol. It works with the account's task lists, including the built-in default list identified by `@default`, and can inspect or change the tasks within them. The server supports titles, notes, date-only due dates, completion state, nesting, and ordering.

Its tool set covers 21 operations. These include listing, creating, and updating task lists and tasks; moving tasks between positions, parents, and lists; marking tasks complete; reopening completed tasks; clearing completed tasks from a list view; and deleting tasks or lists. A raw API request tool provides access to Google Tasks methods without a dedicated wrapper.

The server distinguishes ordinary reads, changes, reversible completion actions, and destructive operations so an MCP client can present suitable confirmation prompts. Completing a task can be undone with `reopen_task`. Deleting a task is permanent, and deleting a list also removes its tasks.

## How it works

Google Tasks MCP uses Google OAuth 2.0 rather than an API key. A user can tell the assistant to connect Google Tasks, after which the server guides the OAuth setup, receives Google's redirect on `127.0.0.1`, uses PKCE, and stores the resulting tokens itself. This conversational flow avoids requiring credentials during installation or a configuration-file edit.

Task dates follow the Google Tasks API: only the calendar date is stored. A requested time of day is not scheduled, so time-specific instructions belong in task notes. Ordering and nesting are changed with `move_task`; the API's position field is read-only.

The server does not provide server-side search or sorting. It returns tasks and lets the AI client filter the results. Recurring tasks cannot be created through the API. Tasks originating in Google Docs or Google Chat can be read, but they cannot be created or moved to another list through this API; deleting one also affects its originating document.

## Setup and configuration

Node.js 20 or newer and a Google account are required. Install the npm stdio package with the `@latest` tag through an MCP client, for example:

```bash
npx -y mcp-google-tasks@latest
```

Codex and Claude Code can add that command as an stdio server. Claude Desktop, Cursor, and VS Code also have documented stdio configurations for the package. Claude Desktop's current extension path expects an `.mcpb` bundle, while this project publishes an npm stdio package; local configuration is available in desktop builds that still support it.

For a manual credential setup, the documented environment variables are `GOOGLE_TASKS_CLIENT_ID`, `GOOGLE_TASKS_CLIENT_SECRET`, and `GOOGLE_TASKS_REFRESH_TOKEN`. The conversational connection flow can establish access without entering those values at installation time. Google access uses the Tasks scope and does not request Drive, Calendar, or Gmail access.

## Tools and capabilities

Typical workflows include:

- Listing task lists and open or completed tasks.
- Creating task lists, tasks, notes, subtasks, and date-only due dates.
- Updating titles, notes, and due dates.
- Moving tasks to another list, changing their order, or nesting them under another task.
- Completing and reopening tasks.
- Clearing completed tasks or deleting individual tasks and lists.
- Calling the underlying Google Tasks API when a dedicated tool is unavailable.

Read operations leave Google Tasks unchanged. Creation, updates, moves, and completion alter the account, while clearing and deletion are destructive actions.

_Full upstream README: https://allmcps.com/mcp/google-tasks-mcp/readme_