# 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.

[![npm](https://img.shields.io/npm/v/@oskarengl/google-tasks-mcp)](https://www.npmjs.com/package/@oskarengl/google-tasks-mcp)

```bash
npx @oskarengl/google-tasks-mcp auth
```

**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](https://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. Authorize

```bash
npx @oskarengl/google-tasks-mcp 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 logged, and it stays on your machine.

### 3. Connect a client

For Claude Code:

```bash
claude mcp add google-tasks -- npx -y @oskarengl/google-tasks-mcp serve
```

For Claude Desktop, add this to `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": ["-y", "@oskarengl/google-tasks-mcp", "serve"]
    }
  }
}
```

On Windows, if your client cannot find a bare `npx`, give the full path to `node.exe` and to the
installed `dist/index.js` instead.

---

## 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` | Add a task; 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 |
| `delete_all_completed_tasks` | Clear out the completed tasks in a list |
| `create_task_list` / `rename_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](https://issuetracker.google.com/issues/192637574). `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.

## Developing

```bash
git clone https://github.com/oskarengl/google-tasks-mcp.git
cd google-tasks-mcp
npm install     # builds dist automatically
npm test        # 89 unit tests, no network
npm run smoke   # launches the built server over stdio and calls every read tool
```

`npm run smoke` reads from your real account but never writes.

## Contact

Bug reports and feature requests are best filed as
[issues](https://github.com/oskarengl/google-tasks-mcp/issues), so the answer is there for the
next person. For anything you would rather not put in public, email oskar.engl@gmx.de.

## License

MIT