# Google Tasks MCP Server

A [Model Context Protocol](https://modelcontextprotocol.io/) (MCP) server for Google Tasks. Lets AI assistants list, create, update, delete, and complete tasks via the [Google Tasks API](https://developers.google.com/tasks).

## Why this exists

I prefer Google Tasks over Google Calendar for managing todos. The excellent [google-calendar-mcp](https://github.com/nspady/google-calendar-mcp) project only covers the Calendar API, so I built this quick-and-dirty companion to fill the gap. If you'd like to fold Tasks support into that project, PRs are welcome there.

## Quick Start

### 1. Enable the Google Tasks API

1. Go to the [Google Cloud Console](https://console.cloud.google.com)
2. Create a new project or select an existing one
3. Enable the [Google Tasks API](https://console.cloud.google.com/apis/library/tasks.googleapis.com) (make sure the correct project is selected in the top bar)
4. Create OAuth 2.0 credentials:
   - Go to [Credentials](https://console.cloud.google.com/apis/credentials)
   - Click **Create Credentials** > **OAuth client ID**
   - Choose **Desktop app** as the application type
   - Download the JSON file (you'll reference its path below)
5. Configure the [OAuth consent screen](https://console.cloud.google.com/apis/credentials/consent):
   - Add your email as a **Test User**
   - Note: test-mode tokens expire after 7 days (see [Limitations](#limitations))

### 2. Install

Add to your MCP client config (Cursor, Claude Desktop, etc.):

```json
{
  "mcpServers": {
    "google-tasks": {
      "command": "npx",
      "args": ["-y", "@scottie-will/google-tasks-mcp"],
      "env": {
        "GOOGLE_OAUTH_CREDENTIALS": "/path/to/your/gcp-oauth.keys.json"
      }
    }
  }
}
```

### 3. Authenticate

**Option A — CLI (recommended for first run):**

```bash
GOOGLE_OAUTH_CREDENTIALS=/path/to/gcp-oauth.keys.json npx @scottie-will/google-tasks-mcp auth
```

Complete the OAuth flow in your browser, then restart your MCP client.

**Option B — Via the agent:**

Ask your AI assistant to "authenticate with Google Tasks". The `authenticate` tool will return a URL to visit in your browser. After completing sign-in, tell the agent to verify authentication.

## Available Tools

| Tool | Description |
|------|-------------|
| `authenticate` | Start or verify Google OAuth authentication |
| `list-task-lists` | List all task lists for the authenticated user |
| `list-tasks` | List tasks with optional date filtering and completion status |
| `get-task` | Get a specific task by ID |
| `create-task` | Create a new task (supports subtasks via `parent`) |
| `update-task` | Update an existing task (partial updates supported) |
| `delete-task` | Permanently delete a task |
| `complete-task` | Mark a task as completed |

## Environment Variables

| Variable | Required | Description |
|----------|----------|-------------|
| `GOOGLE_OAUTH_CREDENTIALS` | Yes | Path to your OAuth credentials JSON file |
| `GOOGLE_TASKS_MCP_TOKEN_PATH` | No | Custom path for token storage (default: `~/.config/google-tasks-mcp/tokens.json`) |

## Limitations

- **Dates only, no times.** The Google Tasks API stores due dates only — any time component in the `due` field is [silently discarded](https://developers.google.com/tasks/reference/rest/v1/tasks). Workaround: prefix the task title with a 24-hour time (e.g. "0900 Team standup") for manual time-based ordering.
- **Position-based ordering only.** Tasks are returned in position order (the drag-order from the Google Tasks UI). There is no server-side sort by due date — sort client-side after fetching.
- **No pagination.** Each list call returns at most 100 items. Large task lists may be truncated.
- **Test-mode token expiry.** While your GCP app is in test mode, OAuth tokens expire after 7 days. To avoid this, [publish your app to production](https://console.cloud.google.com/apis/credentials/consent) (no verification needed for personal use — Google will show an "unverified app" warning).
- **Single account.** Only one Google account is supported at a time.

For full API details, see the [Google Tasks API reference](https://developers.google.com/tasks/reference/rest).

## Agent Setup Instructions

This server includes built-in `instructions` metadata (via the MCP protocol) that teaches agents how to use it effectively — covering the auth flow, date-only behavior, sorting quirks, `@default` task list conventions, and destructive-operation guardrails. Compatible MCP clients (Cursor, Claude Desktop, etc.) surface these instructions automatically.

If your client supports `serverUseInstructions` in the MCP config, you can also add custom hints. See [incident.io's MCP](https://github.com/incident-io) for an example of thorough server instructions.

## GCP API Access Required

This server requires:

- **API**: [Google Tasks API](https://console.cloud.google.com/apis/library/tasks.googleapis.com) (`tasks.googleapis.com`)
- **OAuth scope**: `https://www.googleapis.com/auth/tasks` (full read/write access to tasks)
- **Credential type**: OAuth 2.0 Client ID — **Desktop app** type

No API key or service account is needed. The OAuth flow runs locally and tokens are stored on your machine at `~/.config/google-tasks-mcp/tokens.json`.

## Credits

- Inspired by and modeled after [google-calendar-mcp](https://github.com/nspady/google-calendar-mcp) by [@nspady](https://github.com/nspady). That project covers the Google Calendar API with multi-account support, recurring events, and much more. If you'd like to add Tasks support there, open a PR — it would be a natural fit.
- Built with the [Model Context Protocol SDK](https://github.com/modelcontextprotocol/typescript-sdk).

## License

MIT