Summary
Connects your MCP client to Google Tasks through a self-hosted server you control with your own OAuth credentials. You get 19 tools covering tasklists and tasks: create, read, update, delete, move, complete, plus specialized views like today, overdue, upcoming, search, and digest. Runs over stdio for local client launches or streamable HTTP for VPS hosting with bearer token auth. Supports multi-account routing so you can point one client at your personal Tasks and another at work. Responses are compact for low-context workflows. Reach for this when you want an AI assistant to read your agenda, add tasks during conversations, or query overdue items without opening the Google Tasks UI.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Public tool metadata for what this MCP can expose to an agent.
14 tools
GOOGLETASKS_CLEAR_TASKSPermanently clears all completed tasks from a specified Google Tasks list; this action is destructive and idempotent.1 params
Permanently clears all completed tasks from a specified Google Tasks list; this action is destructive and idempotent.
Parameters* required
taskliststringThe identifier of the task list from which to clear completed tasks. Use '@default' for the default task list.
GOOGLETASKS_CREATE_TASK_LISTCreates a new task list with the specified title.1 params
Creates a new task list with the specified title.
Parameters* required
tasklist_titlestringTitle for the new task list. The maximum allowed length is 1024 characters.
GOOGLETASKS_DELETE_TASKDeletes a specified task from a given task list in Google Tasks.2 params
Deletes a specified task from a given task list in Google Tasks.
Parameters* required
task_idstringThe unique identifier of the Google Task to be deleted.
tasklist_idstringThe unique identifier of the Google Task list from which the task will be deleted.
GOOGLETASKS_DELETE_TASK_LISTPermanently deletes an existing Google Task list, identified by `tasklist_id`, along with all its tasks; this operation is irreversible.1 params
Permanently deletes an existing Google Task list, identified by `tasklist_id`, along with all its tasks; this operation is irreversible.
Parameters* required
tasklist_idstringUnique identifier of the Google Task list to be deleted.
GOOGLETASKS_GET_TASKUse to retrieve a specific Google Task if its `task_id` and parent `tasklist_id` are known.2 params
Use to retrieve a specific Google Task if its `task_id` and parent `tasklist_id` are known.
Parameters* required
task_idstringUnique identifier of the Google Task to retrieve.
tasklist_idstringUnique identifier of the Google Tasks list containing the task.
GOOGLETASKS_GET_TASK_LISTRetrieves a specific task list from the user's Google Tasks if the `tasklist_id` exists for the authenticated user.1 params
Retrieves a specific task list from the user's Google Tasks if the `tasklist_id` exists for the authenticated user.
Parameters* required
tasklist_idstringThe unique identifier of the task list to retrieve, assigned by Google Tasks when the list is created.
GOOGLETASKS_INSERT_TASKCreates a new task in a given `tasklist_id`, optionally as a subtask of an existing `task_parent` or positioned after an existing `task_previous` sibling, where both `task_parent` and `task_previous` must belong to the same `tasklist_id` if specified. IMPORTANT: Date fields (d...12 params
Creates a new task in a given `tasklist_id`, optionally as a subtask of an existing `task_parent` or positioned after an existing `task_previous` sibling, where both `task_parent` and `task_previous` must belong to the same `tasklist_id` if specified. IMPORTANT: Date fields (d...
Parameters* required
idstringUnique identifier for the task. Generated by Google Tasks API when creating a task. Used for updating or deleting existing tasks.
duestringDue date for the task (optional). NOTE: Google Tasks only stores the date portion - any time provided will be normalized to midnight UTC by the API.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
etagstringETag of the resource for concurrency control. Prevents accidental overwrites when multiple clients modify the same task. Auto-generated by the API.
notesstringAdditional details or description for the task. Supports plain text only (no HTML/markdown). Maximum 8192 characters. Example: 'Include Q3 sales data and projections'
titlestringTitle/name of the task (REQUIRED). This is the main text displayed for the task. Maximum 1024 characters. Example: 'Complete quarterly report'
hiddenbooleanWhether the task is hidden from the default view. Hidden tasks can still be accessed via API but won't show in UI. Default: false
statusstringCurrent status of the task (REQUIRED). Must be either 'needsAction' (task is pending) or 'completed' (task is done). Default: 'needsAction'one of
needsAction · completeddeletedbooleanWhether the task has been deleted. Deleted tasks are marked but not immediately removed, allowing for recovery. Default: false
completedstringDate/time when the task was marked as completed. Only applicable when status='completed'. Unlike 'due', this field preserves the time component.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
task_parentstringIdentifier of an existing task to serve as parent; if provided, creates a subtask, otherwise a top-level task in the specified list.
tasklist_idstringIdentifier for the Google Task list where the new task will be created. Use actual task list IDs, not '@default'. You can get list IDs using 'List Task Lists' action.
task_previousstringIdentifier of an existing task after which the new task will be placed, at the same hierarchical level (as a sibling).
GOOGLETASKS_LIST_TASK_LISTSFetches the authenticated user's task lists from Google Tasks; results may be paginated.2 params
Fetches the authenticated user's task lists from Google Tasks; results may be paginated.
Parameters* required
pageTokenstringToken for the page of results to return; omit for the first page, use `nextPageToken` from a previous response for subsequent pages.
maxResultsintegerMaximum number of task lists to return per page.default: 20
GOOGLETASKS_LIST_TASKSRetrieves tasks from a Google Tasks list; all date/time strings must be RFC3339 UTC, and `showCompleted` must be true if `completedMin` or `completedMax` are specified.11 params
Retrieves tasks from a Google Tasks list; all date/time strings must be RFC3339 UTC, and `showCompleted` must be true if `completedMin` or `completedMax` are specified.
Parameters* required
dueMaxstringExclude tasks due after this date.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
dueMinstringExclude tasks due before this date.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
pageTokenstringToken from a previous list operation for fetching a specific page; if omitted, retrieves the first page.
maxResultsintegerMaximum number of tasks to return. API default: 20, maximum: 100.
showHiddenbooleanInclude hidden tasks. Defaults to false.
updatedMinstringLower bound for task's last modification time (for syncing).
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
showDeletedbooleanInclude deleted tasks. Defaults to false.
tasklist_idstringIdentifier of the task list. Use '@default' for the user's primary task list.
completedMaxstringExclude tasks completed after this date.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
completedMinstringExclude tasks completed before this date.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
showCompletedbooleanInclude completed tasks. Defaults to true. (See action docstring for interaction with `completedMin`/`Max`).
GOOGLETASKS_MOVE_TASKMoves the specified task to another position in the destination task list.5 params
Moves the specified task to another position in the destination task list.
Parameters* required
taskstringTask identifier.
parentstringNew parent task identifier. If not provided, the task is moved to the top level.
previousstringNew previous sibling task identifier. If not provided, the task is moved to the first position among its siblings.
taskliststringTask list identifier.
destinationTaskliststringDestination task list identifier. If set, the task is moved to this list; otherwise, it remains in its current list.
GOOGLETASKS_PATCH_TASKPartially updates an existing task (identified by `task_id`) within a specific Google Task list (identified by `tasklist_id`), modifying only the provided attributes from `TaskInput` (e.g., `title`, `notes`, `due` date, `status`) and requiring both the task and list to exist.11 params
Partially updates an existing task (identified by `task_id`) within a specific Google Task list (identified by `tasklist_id`), modifying only the provided attributes from `TaskInput` (e.g., `title`, `notes`, `due` date, `status`) and requiring both the task and list to exist.
Parameters* required
idstringUnique identifier for the task. Generated by Google Tasks API when creating a task. Used for updating or deleting existing tasks.
duestringDue date for the task (optional). NOTE: Google Tasks only stores the date portion - any time provided will be normalized to midnight UTC by the API.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
etagstringETag of the resource for concurrency control. Prevents accidental overwrites when multiple clients modify the same task. Auto-generated by the API.
notesstringAdditional details or description for the task. Supports plain text only (no HTML/markdown). Maximum 8192 characters. Example: 'Include Q3 sales data and projections'
titlestringTitle/name of the task (REQUIRED). This is the main text displayed for the task. Maximum 1024 characters. Example: 'Complete quarterly report'
hiddenbooleanWhether the task is hidden from the default view. Hidden tasks can still be accessed via API but won't show in UI. Default: false
statusstringCurrent status of the task (REQUIRED). Must be either 'needsAction' (task is pending) or 'completed' (task is done). Default: 'needsAction'one of
needsAction · completeddeletedbooleanWhether the task has been deleted. Deleted tasks are marked but not immediately removed, allowing for recovery. Default: false
task_idstringIdentifier of the Google Task to be updated within the specified task list.
completedstringDate/time when the task was marked as completed. Only applicable when status='completed'. Unlike 'due', this field preserves the time component.
Google Tasks API requires dates in RFC3339 format (e.g., 2025-09-22T13:48:27Z).
We automatically convert various human-readable formats to RFC3339:
Accepted formats:
• 2025-09-28T23:59:00Z → RFC3339/ISO-8601 format (preferred) - September 28, 2025 at 11:59 PM UTC
• 28 Sep 2025 → Simple date format - Will be converted to midnight UTC on that date
• 11:59 PM, 22 Sep 2025 → Time with date - Assumes UTC timezone if not specified
• 1:00 PM, 21 Sep 2025 → 12-hour format with date - Converted to 13:00 UTC
• UTC-5:30, 6:50 PM → With timezone offset - Converted to UTC automatically
• UTC+1, 11:59 PM, 31 Dec → Timezone with date - Next occurrence of Dec 31
• 2025-09-21T15:30:00+02:00 → RFC3339 with timezone offset
Note: If no timezone is specified, UTC is assumed. Dates without times default to midnight UTC.
tasklist_idstringIdentifier of the Google Task list that contains the task to be updated.
GOOGLETASKS_PATCH_TASK_LISTUpdates the title of an existing Google Tasks task list.2 params
Updates the title of an existing Google Tasks task list.
Parameters* required
tasklist_idstringThe unique identifier of the task list to be updated.
updated_titlestringThe new title for the task list.
GOOGLETASKS_UPDATE_TASKUpdates the specified task.6 params
Updates the specified task.
Parameters* required
duestringDue date of the task (RFC 3339 timestamp).
taskstringTask identifier.
notesstringNotes describing the task.
titlestringTitle of the task.
statusstringStatus of the task ("needsAction" or "completed").
taskliststringTask list identifier.
GOOGLETASKS_UPDATE_TASK_LISTUpdates the authenticated user's specified task list.2 params
Updates the authenticated user's specified task list.
Parameters* required
titlestringTitle of the task list. Maximum length allowed: 1024 characters.
tasklist_idstringTask list identifier.
Google Tasks MCP Server
Connect an MCP-compatible client to Google Tasks through a private server you run yourself. The server exposes compact tools for reading, searching, summarizing, creating, completing, updating, deleting, and moving Google Tasks.
This project is for self-hosted use. You provide your own Google Cloud OAuth credentials, connect your own Google account, and keep tokens in your own SQLite database.
What You Get
- 19 MCP tools for Google Tasks.
- Local stdio mode for desktop/client-launched setups.
- Streamable HTTP mode for local HTTP or VPS hosting.
- Bearer-token HTTP auth, plus optional OAuth 2.0 gateway mode for MCP clients that support OAuth.
- Compact responses designed for low-context assistant workflows.
- Optional operator-managed multi-account bearer-token routing, for familiar setups such as one personal account and one work account.
Choose A Transport
| Use case | Transport | Auth |
|---|---|---|
| MCP client starts the process directly | stdio | No MCP_BEARER_TOKEN needed |
| Local HTTP server | Streamable HTTP at http://127.0.0.1:8787/mcp | Bearer token |
| VPS or other host | Streamable HTTP at https://your-domain.example/mcp | Bearer token or OAuth gateway |
For deeper hosting and distribution guidance, see MCP_SERVER_GUIDE.md and DISTRIBUTION.md.
Install
git clone https://github.com/ebmurha/google-tasks-mcp.git
cd google-tasks-mcp
python3.11 -m venv .venv
. .venv/bin/activate
pip install -e .
cp .env.example .env
Generate a bearer token if you will run HTTP mode:
python -c "import secrets; print(secrets.token_urlsafe(48))"
Put the generated value in .env as MCP_BEARER_TOKEN. Do not commit .env.
Google Cloud Setup
- Create or open a Google Cloud project.
- Enable the Google Tasks API.
- Configure the OAuth consent screen.
- Create an OAuth 2.0 Client ID.
Recommended for local HTTP, VPS, Docker, and other server-style installs:
- Application type: Web application
- Local redirect URI:
http://127.0.0.1:8787/callback - Hosted redirect URI:
https://your-domain.example/callback .env: setGOOGLE_CLIENT_ID,GOOGLE_CLIENT_SECRET, andGOOGLE_REDIRECT_URI
Local-only alternative:
- Application type: Desktop app
- Download the OAuth client JSON outside this repo.
- Set
GOOGLE_OAUTH_KEYS_PATHto that file path. - Leave
GOOGLE_CLIENT_IDandGOOGLE_CLIENT_SECRETempty unless you want env vars to override the JSON file.
Example .env for a local web OAuth client:
GOOGLE_CLIENT_ID=your-client-id.apps.googleusercontent.com
GOOGLE_CLIENT_SECRET=your-client-secret
GOOGLE_REDIRECT_URI=http://127.0.0.1:8787/callback
MCP_BEARER_TOKEN=your-generated-token
DB_PATH=./google-tasks.db
BIND_HOST=127.0.0.1
BIND_PORT=8787
If the Google OAuth app is in Testing mode, add every Google account you bootstrap as a test user, such as both personal and work accounts.
GOOGLE_CLIENT_ID / GOOGLE_CLIENT_SECRET / GOOGLE_OAUTH_KEYS_PATH identify the Google Cloud OAuth app, not the Google Tasks user account. One OAuth client JSON can be reused for several Google users. Each bootstrap run stores a separate refresh token for the Google account you authorize in the browser.
Bootstrap Google OAuth
Run this once per Google account you want the server to access:
google-tasks-mcp-bootstrap
Open the printed URL, approve access, and paste the authorization code back into the terminal.
For multiple trusted accounts on one HTTP server, create one stored bearer token per account and bootstrap each account separately:
google-tasks-mcp-create-bearer-token --account-id personal --label "Personal account"
google-tasks-mcp-bootstrap --account-id personal
google-tasks-mcp-create-bearer-token --account-id work --label "Work account"
google-tasks-mcp-bootstrap --account-id work
Use each printed bearer token only in the matching account's MCP client. The server stores only bearer-token hashes.
Start The Server
HTTP mode:
python -m google_tasks_mcp --transport http
Health check:
curl http://127.0.0.1:8787/healthz
Expected response:
{"ok": true}
Stdio mode:
python -m google_tasks_mcp --transport stdio
Configuration check:
python -m google_tasks_mcp --check
Connect An MCP Client
Remote or local HTTP:
URL: http://127.0.0.1:8787/mcp
Auth: Bearer <MCP_BEARER_TOKEN>
For a VPS, replace the URL with your HTTPS endpoint:
URL: https://your-domain.example/mcp
Auth: Bearer <MCP_BEARER_TOKEN>
Local stdio:
{
"command": "/path/to/google-tasks-mcp/.venv/bin/python",
"args": ["-m", "google_tasks_mcp", "--transport", "stdio"]
}
MCP_BEARER_TOKEN is not required for stdio because the MCP client launches the process locally.
Authentication Modes
Bearer-token mode is the default HTTP mode. /mcp requires Authorization: Bearer <token>.
MCP_BEARER_TOKENroutes to accountdefault.- Tokens created with
google-tasks-mcp-create-bearer-tokencan route different clients to differentaccount_idvalues. - Bearer tokens are displayed once and stored only as hashes.
OAuth 2.0 gateway mode is optional. Enable it when your HTTP MCP client supports OAuth authorization metadata and token refresh.
- Set
MCP_OAUTH_ISSUER,MCP_OAUTH_CLIENT_ID,MCP_OAUTH_CLIENT_SECRET, andMCP_OAUTH_SIGNING_SECRET. - Set
MCP_OAUTH_REDIRECT_URISto the callback URI values accepted by your MCP client. /mcpaccepts OAuth-issued access tokens and the legacy bearer token.- OAuth gateway refresh tokens are stored by hash and rotate on use, so clients can reconnect after server restart.
Leave MCP_OAUTH_REDIRECT_URIS empty to keep OAuth gateway mode disabled.
Tools
The same 19 tools are available over stdio, bearer-token HTTP, and OAuth gateway HTTP modes. Tools expose standard MCP titles, descriptions, and safety hints where the client supports them.
| Group | Tools | Notes |
|---|---|---|
| Tasklists | list_tasklists, create_tasklist, get_tasklist, update_tasklist, delete_tasklist | Tasklist delete requires confirm: true; non-empty lists require force: true. |
| Task reads | list_tasks, get_task | Read from one tasklist. If tasklist is omitted, uses DEFAULT_TASKLIST or Google's first list. |
| Task summaries | today, overdue, upcoming, search, digest | If tasklist is omitted, reads all tasklists and includes tasklist context. |
| Task mutations | clear_completed, add, complete, update, uncomplete, delete, move | Mutate one tasklist/task at a time. clear_completed requires confirm: true. |
All tasklist arguments accept a tasklist ID or exact title. Task title lookup is exact after trimming whitespace and ignores case.
For today, overdue, upcoming, search, and digest, omitting tasklist reads every tasklist. Returned task objects include tasklist_id and tasklist_title; digest labels items with tasklist context.
For list_tasks, clear_completed, single-task tools, and write tools, omitting tasklist uses DEFAULT_TASKLIST, or the first list returned by Google. This prevents unqualified writes from touching every list.
Limitations
These are Google Tasks REST API limits:
- Due dates are date-only. Google drops time-of-day values on task due dates.
- Recurring tasks cannot be created or read through the Google Tasks REST API.
clear_completedhides completed tasks; it does not permanently delete them.
Docker And VPS
Docker:
docker compose up --build
Keep .env, OAuth JSON files, and SQLite databases outside images and public bundles.
VPS/systemd/Caddy templates are in deploy/:
Replace every placeholder domain, path, and user before deploying.
Troubleshooting
Missing bearer token:
- HTTP
/mcprequiresAuthorization: Bearer <token>unless OAuth gateway mode is handling the client. - Stdio mode does not use
MCP_BEARER_TOKEN.
Google OAuth app is in Testing mode:
- Add every bootstrapped Google user as a test user.
- Testing-mode refresh tokens can expire after 7 days.
Callback URI mismatch:
GOOGLE_REDIRECT_URImust exactly match an Authorized redirect URI in Google Cloud.- For local web OAuth, use
http://127.0.0.1:8787/callbackconsistently.
Expired or revoked Google refresh token:
- Run
google-tasks-mcp-bootstrapagain for the affected account. - For multi-account mode, include the same
--account-idyou used before.
OAuth MCP client keeps re-authorizing:
- Ensure the server is running a version with persisted MCP OAuth refresh tokens.
- Check that
DB_PATHpoints to persistent storage and survives restarts. - Verify
MCP_OAUTH_ISSUERis the public HTTPS base URL with no trailing slash.
More Docs
- MCP_SERVER_GUIDE.md explains hosting models, credential boundaries, and public project vs public service choices.
- DISTRIBUTION.md explains registry, bundle, and directory publishing.
- .env.example lists every supported environment variable.
- google-tasks-mcp-specifications.md is the behavioral source of truth.
Tests
pytest
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
GOOGLE_CLIENT_ID*secretGoogle OAuth client ID from the user's Google Cloud project.
GOOGLE_CLIENT_SECRET*secretGoogle OAuth client secret from the user's Google Cloud project.
GOOGLE_REDIRECT_URI*OAuth callback URL for the user's local or hosted server.
DB_PATHPersistent SQLite database path for tokens and cache.
DEFAULT_TASKLISTOptional default tasklist title or ID.