mcp-google-tasks
Manage Google Tasks through 21 MCP tools — task lists, tasks, subtasks, due dates and completion — plus in-chat OAuth connection handling and a raw API escape hatch.
Connect and authenticate: check connection status, get a setup checklist, save the OAuth client JSON by path, start/finish an in-chat OAuth login (PKCE, loopback listener), and log out (revoking the token).
Task lists: list, fetch, create, rename, and delete lists (deleting a list removes all its tasks;
@defaultaddresses the default list).Read tasks: list tasks with filters (due/completed ranges,
updated_minsync, show hidden/deleted/completed/assigned, pagination) and fetch a single task.Create and edit tasks: create tasks with title, notes, date-only due date, and placement under a parent or after a sibling; update title/notes/due date or clear those fields.
Organize: move a task to reorder it, re-parent it as a subtask, or move it to another list — the only way to change order/hierarchy.
Completion: mark tasks complete, reopen them (undo), and clear all completed tasks from a list in one call.
Delete: permanently delete a task (subtasks included) — distinct from completing.
Escape hatch:
raw_requestcalls any Google Tasks API v1 path with GET/POST/PATCH/PUT/DELETE and an auto-attached bearer token.Known limits: due dates are date-only, recurring tasks can't be created, and there is no server-side search or sorting (filter client-side).
Provides tools for managing Google Tasks, including listing, creating, updating, moving, completing/reopening, and deleting tasks and task lists, as well as clearing completed tasks and accessing the raw Google Tasks API.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@mcp-google-tasks Show me my task lists and everything due before Friday in my default list."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Google Tasks MCP
English | Русский
A1 Google Tasks MCP lets an AI app manage Google Tasks in plain language. Plan a project as a task list, break work into subtasks with due dates and notes, mark things done and keep everything in order.
It uses the Google Tasks API with your Google account. It separates reversible completion from permanent deletion and makes the limits of the Tasks API explicit instead of implying that every to-do feature is possible.
21 tools. List, create and update task lists and tasks, move tasks, manage completion, sweep finished work and reach the raw API when a dedicated tool is missing.
Connects from the conversation. Say "connect Google Tasks": the server walks you through the OAuth client, catches Google's redirect on
127.0.0.1with PKCE and keeps the tokens itself — no config files, no restart.Completion is reversible, deletion is not.
complete_taskhas an undo (reopen_task); the delete tools are separate and marked destructive.Due dates are honest. The API stores only the calendar date — the server never pretends to schedule a time of day; times belong in the notes.
Minimal Google scope. A single
tasksscope, without Drive, Calendar or Gmail access.
Start with a read-only question:
Show me my task lists and everything due before Friday in my default list.
Connect the server · Explore use cases · Open technical documentation
See it work in a minute
You: What's still open in the "Website launch" list, and what's due this week?
Assistant: Shows the open tasks with their due dates, notes and subtasks. Nothing changes.
You: Add a task "Send the launch announcement" due Friday as a subtask of "Marketing".
Assistant: Shows the target list, the parent task and the proposed task, then asks for confirmation before creating it.
You: Confirm.
Assistant: Creates the subtask with a Friday due date. It does not complete or delete anything unless you ask separately.
Related MCP server: Google Tasks MCP Server
Contents
Quick start
You need Node.js 20+ and a Google account. Credentials are not required at install time — the server connects from the conversation.
Add the server to your AI app.
Say "connect Google Tasks": the assistant walks you through creating the OAuth client and approving access without editing config files.
Ask the read-only question above.
In the app: open Settings → MCP servers, select Add server, choose STDIO, enter the command npx -y mcp-google-tasks@latest and environment variables GOOGLE_TASKS_CLIENT_ID, GOOGLE_TASKS_CLIENT_SECRET, GOOGLE_TASKS_REFRESH_TOKEN, then select Save and Restart.
From the command line:
codex mcp add google-tasks \
-- npx -y mcp-google-tasks@latestcodex mcp listclaude mcp add \
--transport stdio --scope user google-tasks \
-- npx -y mcp-google-tasks@latestclaude mcp listThe current official path is Settings → Extensions. For a custom desktop extension, open Advanced settings → Extension Developer → Install Extension…, select a .mcpb file and follow the prompts.
This repository currently publishes an npm stdio package and does not contain a .mcpb bundle. For Claude Desktop builds that still support local configuration, use the following JSON stdio configuration as a fallback:
{
"mcpServers": {
"google-tasks": {
"command": "npx",
"args": ["-y", "mcp-google-tasks@latest"]
}
}
}In those builds, save it to ~/Library/Application Support/Claude/claude_desktop_config.json on macOS or %APPDATA%\Claude\claude_desktop_config.json on Windows.
Claude Desktop MCP documentation
Add this to ~/.cursor/mcp.json on macOS/Linux or %USERPROFILE%\.cursor\mcp.json on Windows:
{
"mcpServers": {
"google-tasks": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-tasks@latest"]
}
}
}Run MCP: Open User Configuration and add:
{
"servers": {
"google-tasks": {
"type": "stdio",
"command": "npx",
"args": ["-y", "mcp-google-tasks@latest"]
}
}
}Check it with MCP: List Servers.
What you can ask it to do
See your lists and plan the day
Show my task lists and the open tasks in each one.
What's due this week in the default list? Include subtasks.
What changed since yesterday? Include completed and hidden tasks.
Create and organize work
Create a "Website launch" list with tasks for design, content and QA.
Add a task due Friday with notes, nested under the "Marketing" task.
Move a task to the top of the list, under another task, or into a different list.
Track completion
Mark the review task done — and reopen it if the work comes back.
Sweep every completed task out of the list view in one go.
Show the hidden tasks that were swept earlier.
How a task changes
Tasks live in task lists. Every account has a built-in default list, addressed by the special id
@default;create_tasklistadds more.A task carries a title, notes and a date-only due date — the API discards the time portion, so a time of day belongs in the notes.
Ordering and nesting change only through
move_task; the API'spositionfield is read-only.Completing a task is reversible:
reopen_taskbrings it back. Deleting a task or a list is permanent, and deleting a list removes every task in it.
Recurring tasks cannot be created through the API. Tasks assigned from Google Docs or Chat can be read but not created or moved to another list, and deleting one also removes it in the originating document. There is no server-side search or sorting — the server lists tasks and the AI client filters them.
What can change
Operation | What happens | Confirmation boundary |
Read task lists and tasks | Reads lists, tasks and their filters | No change |
Create a task list or a task | Adds a list or an open task | Changes Google Tasks |
Update a task or rename a list | Changes a title, notes or due date | Changes a task |
Move a task | Changes order, nesting or the containing list | Changes a task |
Complete or reopen a task | Toggles completion status | Reversible change |
Clear completed tasks | Sweeps every completed task in a list out of view | Destructive |
Delete a task or a task list | Removes the task, or the list with everything in it | Destructive |
Raw API request | Can call API methods without a dedicated tool | Potentially destructive |
The AI client controls confirmation prompts. The server marks reads, writes and destructive tools so the client can distinguish an inspection from a live change.
Getting access
Google Tasks requires OAuth 2.0; an API key is not enough. There are two ways in, and the first one needs no configuration files.
Connect from the chat (recommended)
Say "connect Google Tasks" and the assistant runs the flow with you:
setup_instructionsprints the checklist: create or select a Google Cloud project, enable Google Tasks API, configure the consent screen and create a Desktop app OAuth client.Download that client's JSON ("Download JSON") and give the assistant its path —
set_clientstores it owner-only. The secret never goes through the conversation.start_loginreturns a Google consent link. Open it on this machine and approve; the code comes back to a one-shot listener on127.0.0.1(PKCE), never through the chat.finish_loginexchanges the code and saves the tokens to~/.config/mcp-google-tasks/credentials.json(mode 0600) and verifies them with a real Google Tasks API call — so an API that is still switched off is caught right there.
The tokens are re-read on every call, so the connection works immediately — no restart of the AI app. auth_status shows what is connected, logout revokes and deletes it.
Environment variables (CI, unattended installs)
Create or select a Google Cloud project and enable Google Tasks API.
Configure the OAuth consent screen and create a Desktop app OAuth client.
Authorize the Google account that owns the tasks. The OAuth 2.0 Playground can obtain the refresh token when Use your own OAuth credentials is enabled.
Request the scope:
https://www.googleapis.com/auth/tasks
Testing-mode OAuth refresh tokens can expire after seven days. Publish the OAuth app, or use an Internal app in a Workspace domain, when you need long-lived access. Treat the client secret and refresh token as passwords.
Configuration
Every variable is optional — with none of them the server connects from the chat.
Variable | Required | Description |
| No* | OAuth client ID. |
| No* | OAuth client secret. |
| No* | OAuth refresh token. |
| No* | Short-lived alternative to the OAuth trio. |
| No | Fixed loopback port for the in-chat login; useful over SSH port forwarding. |
| No | Google Tasks API base URL override. |
| No | Per-request timeout; default |
| No | Temporary-error retries; default |
* Provide either the OAuth trio or an access token.
Without credentials the server still starts and completes the MCP handshake; the first tool call then fails with a message naming the variables to set and asking for a restart.
Data, limits and background work
Requests go to Google Tasks. The local server refreshes Google OAuth tokens and calls the Tasks API. Its anonymous telemetry contains an installation ID, package version, AI client and platform versions, and tool names — never OAuth tokens, task content, tool arguments or prompts. For each tool call it also sends the outcome and, on failure, an excerpt of the error text with e-mails, addresses, tokens, numbers of 4+ digits and quoted text replaced by
#; a value from your request can appear in it if the error text contains it. SetASKADS_TELEMETRY=0to opt out.Google applies a daily quota. The Tasks API has a courtesy limit of 50,000 queries per day per project. On
429, the server uses backoff; reads also retry after network and5xxerrors, while writes are not replayed after an uncertain failure — check the outcome withget_taskinstead.There is no background polling. The server runs only when called.
list_taskssupports incremental sync through theupdated_minfilter, so an AI app with scheduled tasks can check for changes periodically without re-reading everything.
Technical documentation
MCP capability catalog — task-oriented pages for every tool.
Support
Found a bug or need a scenario? Create an issue or write in Telegram.
Available Tools
21 toolsauth_statusGoogle connection statusARead-onlyIdempotent
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.
Inputs: no named parameters.
clear_completed_tasksClear completed tasksADestructive
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.
Inputs: tasklist_id (required).
complete_taskComplete a taskADestructiveIdempotent
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.
Inputs: task_id (required), tasklist_id (required).
create_taskCreate a taskA
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.
Inputs: title (required), tasklist_id (required), due, notes, +2 more.
create_tasklistCreate a task listA
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.
Inputs: title (required).
delete_taskDelete a taskADestructive
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.
Inputs: task_id (required), tasklist_id (required).
delete_tasklistDelete a task listADestructive
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.
Inputs: tasklist_id (required).
finish_loginFinish the Google loginAIdempotent
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.
Inputs: no named parameters.
get_taskGet a taskARead-onlyIdempotent
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.
Inputs: task_id (required), tasklist_id (required).
get_tasklistGet a task listARead-onlyIdempotent
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.
Inputs: tasklist_id (required).
list_tasklistsList task listsARead-onlyIdempotent
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.
Inputs: page_size, page_token.
list_tasksList tasksARead-onlyIdempotent
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.
Inputs: tasklist_id (required), due_max, due_min, page_size, +8 more.
logoutDisconnect from GoogleADestructive
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.
Inputs: no named parameters.
move_taskMove a taskA
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.
Inputs: task_id (required), tasklist_id (required), parent, previous, +1 more.
raw_requestRaw Google Tasks API callADestructive
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//tasks/", 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//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.
Inputs: path (required), body, method.
reopen_taskReopen a taskADestructiveIdempotent
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.
Inputs: task_id (required), tasklist_id (required).
set_clientSave the OAuth clientAIdempotent
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.
Inputs: path (required).
setup_instructionsSetup instructionsARead-onlyIdempotent
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.
Inputs: no named parameters.
start_loginStart the Google loginAIdempotent
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.
Inputs: no named parameters.
update_taskUpdate a taskADestructiveIdempotent
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.
Inputs: task_id (required), tasklist_id (required), due, notes, +3 more.
update_tasklistRename a task listADestructiveIdempotent
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.
Inputs: title (required), tasklist_id (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct resource+action, and the descriptions actively cross-reference each other to prevent misselection (update_task explicitly excludes status/reorder, delete_task vs complete_task vs clear_completed_tasks are carefully separated). The only potential overlap is raw_request vs the typed tools, but it is clearly framed as a last-resort escape hatch. Auth tools map to discrete steps of a single OAuth flow rather than duplicating each other.
Overwhelmingly consistent snake_case verb_noun: list_tasklists, get_tasklist, create_task, update_task, move_task, delete_task, complete_task, reopen_task, clear_completed_tasks. Minor deviations exist in the auth group (auth_status, setup_instructions are noun phrases, logout is a bare verb), but they remain readable and predictable. Nothing is ambiguous or chaotically styled.
21 tools is heavy for a task-list domain, largely because six tools are dedicated to an in-chat OAuth flow (set_client, setup_instructions, start_login, finish_login, auth_status, logout) rather than the tasks API itself. Each auth tool is defensible given the stated credential UX, but the overall surface is broader than the core purpose warrants. The 14 task/list tools are reasonably scoped.
Full lifecycle coverage: CRUD for lists and tasks, hierarchy/reorder via move_task, reversible completion (complete_task/reopen_task), bulk clear_completed_tasks, deletion with soft-delete visibility, and raw_request as an escape hatch for uncovered API shapes. Remaining gaps are mostly API limitations (no recurrence, no search) but there is no bulk delete of open tasks and no cross-list task query.
Maintenance
Related MCP Connectors
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
AI-native task management: list, create, update and archive tasks with rich context for AI agents
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLMs like Claude to manage Google Tasks by listing, creating, updating, completing, and deleting tasks and task lists, including setting due dates and notes.MIT
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to manage Google Tasks through natural language interactions. Supports creating, updating, deleting, searching, and listing tasks with secure OAuth2 authentication.115 npm10MIT
- AlicenseNot gradedqualityDmaintenanceEnables AI assistants to manage Google Tasks, including listing, creating, updating, deleting, and completing tasks via the Google Tasks API.52 npm1MIT
- FlicenseNot gradedqualityDmaintenanceEnables managing Google Tasks through natural language, including listing, creating, completing, deleting, and updating tasks.1-