Google Tasks MCP
Provides tools to read and manage Google Tasks through Google's official API, including listing and searching tasks, generating task digests, creating and updating tasks, changing completion status, moving tasks between lists, deleting tasks, and managing task lists.
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., "@Google Tasks MCP show me a digest of my open tasks, including anything overdue"
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
A local MCP server that lets an AI assistant read and manage Google Tasks through Google's official API. Built in Python with the official MCP SDK; no third-party backend or model API key is needed by the server.
Version 0.2.0 · Python 3.11+ · MCP SDK 2.3.0 · stdio transport
What it does
Tools | Purpose |
| Local configuration and stored permission status, without secrets |
| Read task lists and exact IDs |
| Read tasks, notes, completion state, and calendar dates |
| Search titles and notes across one or multiple lists |
| Group open tasks into overdue, today, upcoming, and undated |
| Create tasks and patch selected fields |
| Change completion status |
| Reorder, reparent, or move between lists using Google's native API |
| Delete an exact task after confirmation and a title check |
| Manage lists |
| Hide completed tasks; this does not permanently delete them |
Related MCP server: google-tasks-mcp
Setup
Create and activate a virtual environment from this folder:
python3.13 -m venv .venv
source .venv/bin/activate
python -m pip install -e ".[dev]"Python 3.11+ works. The commands above use the Python 3.13 installation used during development. A tested development dependency snapshot is provided in requirements.lock; install it first if you want those exact dependency versions, then install this project with python -m pip install -e . --no-deps.
Create a project under an account you control and enable Google Tasks API.
Configure Google Auth Platform → Branding, with an External audience for a personal Gmail app.
Add the Google account containing your tasks under Audience → Test users.
Under Data Access, add
https://www.googleapis.com/auth/tasks.readonlyfor reads. Addhttps://www.googleapis.com/auth/taskswhen enabling writes.Create an OAuth client with type Desktop app and select Use this client for an AI-powered agent.
Download its JSON and save it as
credentials.jsonin this folder. Both credentials and tokens are ignored by Git.
The Cloud project owner and the Google Tasks user can be different accounts. School/work accounts may require administrator approval. See Google's quickstart.
Authorize read access:
python auth.pyExisting read-only authorization continues to work. To enable the write tools, explicitly grant Google's write scope:
python auth.py --writeTo choose another account or replace revoked authorization, add --force; use --write --force to retain write access. Authentication has a three-minute browser timeout, uses PKCE and a loopback callback, and replaces the token atomically with owner-only permissions. The MCP server never opens a sign-in browser.
Run and test in Inspector
Install Node.js if needed for Inspector (the development machine uses Node 24). From this folder:
npx @modelcontextprotocol/inspector .venv/bin/python server.pyConnect, list tools, then:
Call
list_task_listsand copy a list'sid.Call
list_taskswith that value astask_list_id.Call
get_task_digestwithtimezone="America/Los_Angeles", or your own IANA timezone.
Keep Terminal running while using Inspector. Control+C stops the process; Control+X exits nano only.
To expose only the seven read tools, even if Google granted write access:
python server.py --read-onlyAfter installing the project, gtasks-mcp and gtasks-auth are also available as commands. For a wheel installation outside this checkout, set absolute GTASKS_CREDENTIALS_PATH and GTASKS_TOKEN_PATH paths to a private configuration directory.
Connect an MCP client
examples/mcp-client.json shows the conventional configuration shape. Replace /absolute/path/to/google-tasks-mcp with this checkout's actual path. Clients have different configuration locations; consult the chosen client's documentation. The server speaks standard stdio MCP and does not run an HTTP listener for tools.
Environment variable | Default | Purpose |
| Checkout's | Desktop OAuth credentials |
| Checkout's | Private stored user authorization |
|
| Hide all write tools and reject writes in the API client |
|
| Default digest timezone |
Set these in your shell or MCP client's environment. .env.example documents them; .env files are not automatically loaded. get_server_info inspects local token metadata; it does not prove a token is still accepted by Google.
Behavior that matters
Use IDs. Two lists or tasks can have the same title. Mutations never guess which title match you meant.
Pages are explicit.
list_tasksandlist_task_listsreturnnext_page_token. Pass it back with the same filters; an empty filtered page can still have another page.Search is bounded. Search/digest scan at most
max_tasks(default 1,000, max 5,000),max_lists(default/max 100), and 100 task pages.truncated=truemeans incomplete results. Search returns at mostlimitmatches (default 20, max 100); restrict to a list or raise the budget when needed. Never interpret an incomplete empty search as proof that no matching task exists.Dates have no time of day. Supply
YYYY-MM-DD, including for inclusive date filters. Returnedduevalues use that same format. No timed reminders or recurrence editing are claimed.Digests stay compact. Each group returns up to
limit_per_grouptasks (default 20, max 100), plus counts from the scanned data.scan_truncateddistinguishes a partial scan from output shortened to the group limit. Counts from a partial scan are lower bounds.Notes stay intact. Updates use PATCH; omitted fields are preserved.
notes=""clears notes;clear_due=trueremoves a date.dueandclear_duecannot be combined.Completed tasks can be hidden.
include_completed=truerequests both completed and hidden tasks, including tasks finished in Google's own apps.Writes aren't replayed automatically. Transient reads retry at most twice with backoff. A timeout or server failure during a write reports an unknown outcome; read the affected list before retrying. This cannot guarantee deduplication if a caller repeats a successful creation.
Deletion is deliberate. Deletion requires
confirm=trueand an exactexpected_title. Nonempty lists requireallow_nonempty=true. Confirmation flags are execution guardrails, not evidence of human consent: your MCP host must obtain approval. Other clients can edit data between the title check and deletion; this is not a transaction.Recurrence isn't detectable. Google's API does not expose recurrence rules. This implementation does not guess from duplicate titles and cannot guarantee deletion affects only one occurrence. Native cross-list moves of repeating tasks may be rejected by Google.
Assigned tasks are limited. Default task listings exclude tasks assigned from Docs/Chat. Such tasks have additional API restrictions; this project focuses on ordinary personal tasks.
See the Google Task resource, list parameters, and native move API.
Development and verification
python -m unittest discover -s tests -v
python -m ruff check .
python -m ruff format --check .
python -m buildTests use synthetic credentials and fake Google responses. They never read your token or change Google Tasks. The protocol integration tests launch a real MCP subprocess with a fake Google service and cover reads, writes, validation, and read-only mode. GitHub Actions runs the checks on Python 3.11 and 3.13 without Google credentials.
For an optional real-account read-only smoke test after authorization:
python scripts/smoke_read.pyIt prints tool names and counts, not task contents or credentials. Real write behavior should be checked in a dedicated sandbox list after write authorization. Automated fake-service tests do not establish all live Google API behavior.
Code map
server.py / auth.py familiar launch commands
gtasks_mcp/server.py MCP descriptions, schemas, annotations, error boundary
gtasks_mcp/client.py Google operations, pagination, search, digest, retry policy
gtasks_mcp/auth.py scope checks, explicit sign-in, refresh, atomic token storage
gtasks_mcp/models.py typed outputs
gtasks_mcp/validation.py calendar dates, IDs, titles, and input limits
gtasks_mcp/config.py environment configuration
tests/ behavior and real-protocol tests using fake Google dataDesign references
This is an independently written implementation inspired by patterns studied in oskarengl/google-tasks-mcp, scottie-will/google-tasks-mcp, girmmy/google-tasks-mcp-server, and ebmurha/google-tasks-mcp. See docs/design.md for the comparison and decisions. Inspiration is credited; this repository does not claim those projects' work as its own.
This project is for one user's local machine. Hosted multi-user OAuth, HTTP serving, recurrence management, background scheduling, offline synchronization, and distributed idempotency are outside its scope. Publishing code on GitHub is separate from deploying a public service.
Troubleshooting
Error | Action |
| Run |
| Add the Tasks write scope in Cloud, then run |
| Review |
| Check the API, Google account permissions, and administrator policies |
| Wait before retrying; avoid repeatedly scanning all lists |
| Read the list before repeating the write |
| Read the exact target again and confirm the intended deletion |
OAuth apps left in Google's External Testing state can receive refresh tokens that expire after seven days for Tasks scopes. Reauthorize when needed and review Google's token-expiration guidance before changing publishing status. A public multi-user OAuth app may have additional verification requirements.
License
MIT. Dependencies retain their respective licenses.
Available Tools
17 toolsclear_completed_tasksADestructiveIdempotent
Hide completed tasks after user confirmation. This does not permanently delete them.
They remain retrievable by list_tasks with include_completed=true.
Inputs: task_list_id (required), confirm. Returns: effect, cleared, task_list_id
complete_taskAIdempotent
Mark a task complete without overwriting its title, notes, or due date.
Inputs: task_id (required), task_list_id (required). Returns: task, operation, task_list_id
create_taskA
Create a task, optionally as a subtask or after a sibling. due is a calendar date, never a time.
Requires Google write permission. Creation is not idempotent: check the list before repeating a call whose outcome is unknown.
Inputs: title (required), task_list_id (required), due, notes, +2 more. Returns: task, operation, task_list_id
create_task_listB
Create a task list. This is not idempotent; duplicate names are permitted by Google.
Inputs: title (required). Returns: id, title, updated
delete_taskADestructive
Permanently delete a task after user confirmation. Requires its exact current title and confirm=true.
Recurrence metadata is not exposed by Google. Do not promise that this deletes only one instance of a repeating task; prefer completion when appropriate.
Inputs: task_id (required), task_list_id (required), expected_title (required), confirm. Returns: deleted, task_id, task_list_id
delete_task_listADestructive
Permanently delete a task list. Requires its exact current title and confirm=true.
Lists with tasks are refused unless allow_nonempty=true after the user approves deletion of their contents. The task check includes hidden and completed tasks.
Inputs: task_list_id (required), expected_title (required), confirm, allow_nonempty. Returns: deleted, task_id, task_list_id
get_server_infoARead-onlyIdempotent
Show local configuration and stored permission status without exposing secrets or contacting Google.
Inputs: no named parameters. Returns: name, version, timezone, transport, +3 more
get_taskARead-onlyIdempotent
Read one task by exact list ID and task ID, including its full notes.
Inputs: task_id (required), task_list_id (required). Returns: id, due, notes, title, +5 more
get_task_digestARead-onlyIdempotent
Group open tasks into overdue, due today, upcoming, and undated.
Supply an IANA timezone such as America/Los_Angeles; the configured default is UTC unless GTASKS_TIMEZONE is set. Upcoming includes tomorrow through today plus days, inclusive. Return at most limit_per_group tasks per group with counts for all scanned matches. truncated=true means some results are omitted; scan_truncated tells whether scanning itself was incomplete.
Inputs: days, timezone, max_lists, max_tasks, +2 more. Returns: today, counts, overdue, undated, +8 more
get_task_listBRead-onlyIdempotent
Read one task list by its exact Google ID.
Inputs: task_list_id (required). Returns: id, title, updated
list_task_listsARead-onlyIdempotent
List one page of task lists with exact IDs. Names need not be unique; continue using next_page_token.
Inputs: page_size, page_token. Returns: task_lists, next_page_token
list_tasksARead-onlyIdempotent
Read one page of tasks from an exact list ID, excluding completed tasks by default.
Date bounds are inclusive YYYY-MM-DD calendar dates. A filtered page can be empty and still have next_page_token. include_completed also requests hidden tasks completed in Google's own apps. Notes are omitted by default. Default listings omit tasks assigned from Docs/Chat.
Inputs: task_list_id (required), due_after, page_size, due_before, +3 more. Returns: tasks, task_list_id, next_page_token
move_taskA
Move using Google's native API, optionally to another list. Never copy then delete.
Omitting parent_id moves to the top level; omitting previous_id places the task first among its siblings. Repeating tasks cannot move between lists. Use IDs returned by this call for subsequent operations.
Inputs: task_id (required), task_list_id (required), parent_id, previous_id, +1 more. Returns: task, operation, task_list_id
rename_task_listAIdempotent
Rename a task list by exact ID, preserving its tasks.
Inputs: title (required), task_list_id (required). Returns: id, title, updated
reopen_taskAIdempotent
Reopen a completed task and clear its completion timestamp.
Inputs: task_id (required), task_list_id (required). Returns: task, operation, task_list_id
search_tasksBRead-onlyIdempotent
Search titles and notes with case-insensitive substring matching.
Omit task_list_id to scan multiple lists. Follow pages up to max_tasks and max_lists; truncated=true means results are incomplete. No fuzzy matching or ambiguous name-based mutations are performed.
Inputs: query (required), limit, max_lists, max_tasks, +2 more. Returns: matches, truncated, limit_reached, scanned_lists, +1 more
update_taskAIdempotent
Patch only supplied fields, preserving all other task data.
Omit notes to preserve them or use an empty string to clear them. Omit due to preserve it or set clear_due=true to remove it. Do not pass both. Use complete_task/reopen_task for status and move_task for hierarchy.
Inputs: task_id (required), task_list_id (required), due, notes, +2 more. Returns: task, operation, task_list_id
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 17 tools
Each tool targets a distinct resource and action: task-list operations, individual task operations, search, digest, and status changes are clearly separated. Read-oriented tools like list_tasks, search_tasks, and get_task_digest overlap only at a high level and are differentiated by scope and output.
All tools use a predictable snake_case verb_noun convention, including create_task_list, get_task, update_task, complete_task, move_task, and delete_task. Minor multi-word nouns like task_list and server_info remain consistent with the pattern.
The 17-tool surface is slightly above the typical 3-15 range but remains reasonable for Google Tasks, which has both task lists and tasks plus status, hierarchy, search, and digest operations. Most tools earn their place, though the server is on the heavier side.
The tool set covers task-list creation, listing, retrieval, renaming, and deletion, plus task creation, retrieval, listing, search, update, completion, reopening, moving, deletion, and clearing completed items. No obvious lifecycle gaps remain for the stated Google Tasks domain.
Maintenance
Related MCP Connectors
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
Task management for people and AI agents, with scoped OAuth access to issues, projects, and docs.
AI-powered to-do list: add, list, complete and organise tasks across lists from any assistant.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Related MCP Servers
- 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.69 npmMIT
- AlicenseNot gradedqualityFmaintenanceEnables AI assistants to manage Google Tasks (list, create, complete, delete tasks) through the Model Context Protocol.396 npm2MIT
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to securely authenticate with Google Tasks and perform full CRUD operations on task lists and tasks, including moving tasks and clearing completed tasks.22 npm-