# gtasks-mcp

![CI](https://github.com/smaurier/gtasks-mcp/actions/workflows/ci.yml/badge.svg)
![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)
![Node >= 20](https://img.shields.io/badge/node-%3E%3D20-brightgreen)

A [Model Context Protocol](https://modelcontextprotocol.io) server for Google Tasks — list, search, create, update, delete, and clear tasks from Claude (or any MCP-compatible client).

Adapted from [zcaceres/gtasks-mcp](https://github.com/zcaceres/gtasks-mcp) (MIT), rebuilt on plain Node/TypeScript instead of Bun, with credentials moved out of the repo entirely (see [Security](#security) below) and a full test suite.

## Setup

### 1. Create a Google Cloud OAuth client

1. Go to the [Google Cloud Console](https://console.cloud.google.com/), create a project (or reuse one).
2. Enable the **Google Tasks API** (APIs & Services → Library).
3. Configure the **OAuth consent screen** (External is fine for personal use — you'll be the only test user).
4. Create credentials → **OAuth client ID** → Application type **Desktop app**.
5. Download the JSON file.

### 2. Install the OAuth client file

```bash
mkdir -p ~/.gtasks-mcp
mv ~/Downloads/client_secret_*.json ~/.gtasks-mcp/oauth-keys.json
```

On Windows: `%USERPROFILE%\.gtasks-mcp\oauth-keys.json`.

### 3. Build and authenticate

```bash
npm install
npm run build
npm run auth
```

This opens a browser window for the Google consent flow. On success, a `credentials.json` (your refresh/access token) is written next to `oauth-keys.json` in `~/.gtasks-mcp/`.

### 4. Register the server with Claude Code

```bash
claude mcp add gtasks -- node /absolute/path/to/gtasks-mcp/dist/index.js
```

## Tools exposed

| Tool | Description |
|---|---|
| `list` | List tasks (all lists, or one via `taskListId`) |
| `search` | Search tasks by title/notes |
| `list-tasklists` | List all task lists |
| `create` | Create a task (`title` required) |
| `update` | Update a task (`id` required) |
| `delete` | Delete a task (`id` required) |
| `clear` | Clear completed tasks from a list |

## Security

- **Credentials never live inside this repo.** `oauth-keys.json` (your Google Cloud OAuth client) and `credentials.json` (your personal access/refresh token, generated by `npm run auth`) are both stored under `~/.gtasks-mcp/` — the OS user-config area, not the project directory. There is no gitignored file inside the repo to accidentally `git add -f`; the secrets aren't reachable from the repo's working tree at all. See `src/config.ts` for the exact paths.
- **`credentials.json` is equivalent to a password** to your Google Tasks — anyone with that file can read/write your tasks. Treat it accordingly (don't email it, don't paste it in a chat, don't back it up somewhere shared).
- **Dependencies**: only `@google-cloud/local-auth`, `googleapis`, and `@modelcontextprotocol/sdk` — all official (Google / Anthropic). No telemetry, no third-party network calls; every request goes to Google's own APIs.
- **Known, accepted transitive vulnerabilities** (`npm audit`, checked 2026-08-25): moderate-severity issues in `esbuild`/`vite` (dev-only tooling, not part of the runtime) and `uuid` (via `gaxios`/`googleapis`, no untrusted-buffer input path in this server's actual usage). Both require a breaking major-version bump upstream to clear; revisit at the next periodic dependency audit rather than force an untested upgrade.

## Development

```bash
npm test        # vitest
npm run lint     # eslint (narrow scope — see eslint.config.js)
npm run typecheck
npm run build
```