google-tasks-mcp

An MCP server for Google Tasks. It uses the official Google Tasks API to read, create, edit, complete, reorder and delete your tasks.

The tool surface mirrors what a person can do in the Google Tasks app, which keeps it plain and adaptable to however you use Tasks. It works with any MCP client, including Claude Code and Claude Desktop, and anything else that speaks MCP over stdio.

Status: read and write tools are implemented and in daily use.

---

Setup

1. Google Cloud (one time, about 15 minutes)

You bring your own OAuth client. Your tasks and tokens never leave your machine.

1. Create a project at console.cloud.google.com.

2. Enable the Google Tasks API (APIs & Services, then Library, then "Google Tasks API", then Enable).

3. Configure the OAuth consent screen: user type External, add the scope https://www.googleapis.com/auth/tasks, and add yourself as a test user.

4. Set the publishing status to "In production." You will see an "unverified app" warning once when you authorize, which you can click through. If you leave the status at Testing, Google revokes your refresh token every 7 days and the server will appear to break for no reason.

5. Credentials, then Create credentials, then OAuth client ID, with application type Desktop app.

6. Download the JSON and save it as:

   • Windows: %APPDATA%\google-tasks-mcp\gcp-oauth.keys.json
   • macOS/Linux: ~/.config/google-tasks-mcp/gcp-oauth.keys.json

   Or put it anywhere and set GTASKS_CREDENTIALS_PATH.

2. Install and authorize

npm install
npm run auth

That opens your browser once, completes a loopback and PKCE flow, and writes a refresh token to %APPDATA%\google-tasks-mcp\tokens.json (or ~/.config/google-tasks-mcp/tokens.json). The token is never stored in this repo and never logged.

3. Verify

npm run smoke

Builds the server, launches it over stdio as a real MCP client would, and calls every read tool against your account. It never writes.

4. Connect a client

For Claude Code:

claude mcp add google-tasks -- node /absolute/path/to/google-tasks-mcp/dist/index.js serve

For Claude Desktop, add this to claude_desktop_config.json:

{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/google-tasks-mcp/dist/index.js", "serve"]
    }
  }
}

Use an absolute path to node if a bare node is not on your client's PATH.

---

Tools

Reading

Tool	Purpose
list_task_lists	Every list, with a short alias and the real id
list_tasks	Tasks by list and/or due-date range; include selects open/completed/all
search_tasks	Substring match over titles and notes
get_task	Full detail for one task, including notes and links

Writing

Tool	Purpose
create_task / create_tasks	Add one task or several; supports notes, due date, subtasks
update_task	Change title, notes or due date. Patch-only, so untouched fields survive
complete_tasks / uncomplete_tasks	Tick off or reopen
move_task	Reorder, reparent, or move to another list
delete_task	Permanent. Guards against repeating-task series
clear_completed	Hide completed tasks in a list
create_task_list / delete_task_list	Manage lists; deletion requires confirm

Set GTASKS_READONLY=1 to run with the read-only Google scope. The write tools are then not registered at all.

list_id accepts a real id, the list title, or the alias shown by list_task_lists, so a handle copied from earlier output resolves without another lookup.

---

Environment variables

Variable	Purpose
GTASKS_CREDENTIALS_PATH	Path to the Desktop-app OAuth client JSON
GTASKS_TOKEN_PATH	Path to the stored token file
GTASKS_READONLY=1	Request tasks.readonly instead of read/write
GTASKS_TIMEZONE	Timezone used to decide what "today" means. Defaults to the host's

The two path overrides let one install serve multiple Google accounts.

---

What the API allows

These are properties of the Google Tasks API itself, and they shape how the server behaves.

Repeating tasks are not available. The API has no recurrence field. Repeating tasks created in the Google Tasks app work normally and roll forward on Google's side, but through the API they appear as ordinary one-off tasks, and a repeat cannot be set. This affects every third-party Google Tasks integration equally.

Because repeats are invisible, deleting one instance through the API can delete the entire series. delete_task guards against this by refusing when another task in the same list has the exact same title, which is the only available hint. Pass force: true to override.

Due dates are calendar dates. The API discards the time portion, so a due time can be neither set nor read.

Other constraints handled internally: results are paginated (maxResults defaults to 20 and caps at 100), updates use patch rather than update so untouched fields survive, and completed tasks become hidden, so reading them needs include set to completed or all. There is no search endpoint, so search_tasks filters client-side.

License

MIT