# Google Tasks MCP — Setup Guide

A local MCP server that connects Claude to your Google Tasks.
Once running, you can ask Claude things like:
- "What tasks do I have this week?"
- "Create a task to call the accountant due Friday"
- "Mark the Xero task as done"

---

## Step 1 — Install dependencies

```bash
cd google-tasks-mcp
npm install
```

---

## Step 2 — Create Google Cloud credentials

1. Go to [https://console.cloud.google.com/](https://console.cloud.google.com/)
2. Create a new project (or use an existing one)
3. Go to **APIs & Services → Library** → search "Google Tasks API" → **Enable**
4. Go to **APIs & Services → Credentials → Create Credentials → OAuth 2.0 Client ID**
   - Application type: **Desktop app**
   - Name: anything (e.g. "Google Tasks MCP")
5. Click **Download JSON** → rename it to `credentials.json`
6. Place `credentials.json` in the `google-tasks-mcp/` folder

> If prompted about OAuth consent screen: set it to **Internal** (if using Google Workspace) or **External** with your own email as a test user.

---

## Step 3 — Authorise (one-time)

```bash
node src/auth.js
```

This opens your browser, asks you to sign in with Google, then saves a `token.json` locally. You only need to do this once.

---

## Step 4 — Register the MCP with Claude

### Claude Desktop (Cowork / Claude.ai desktop)

Edit your Claude config file:

- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`

Add this block inside `"mcpServers"`:

```json
{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/FULL/PATH/TO/google-tasks-mcp/src/index.js"]
    }
  }
}
```

Replace `/FULL/PATH/TO/` with the actual path to this folder.

### Claude Code (CLI)

```bash
claude mcp add google-tasks -- node /FULL/PATH/TO/google-tasks-mcp/src/index.js
```

Restart Claude after adding.

---

## Available Tools

| Tool | What it does |
|---|---|
| `list_task_lists` | List all your task lists |
| `list_tasks` | List tasks (filter by status, show completed) |
| `get_task` | Get a single task by ID |
| `create_task` | Create a new task (title, notes, due date, subtask) |
| `update_task` | Edit title, notes, due date, or status |
| `complete_task` | Mark a task as done |
| `reopen_task` | Reopen a completed task |
| `delete_task` | Permanently delete a task |
| `clear_completed_tasks` | Wipe all completed tasks from a list |

---

## Troubleshooting

**"credentials.json not found"** → Make sure you downloaded it from Google Cloud and placed it in the `google-tasks-mcp/` root folder.

**"token.json not found"** → Run `node src/auth.js` first.

**Token expired** → The server auto-refreshes tokens. If it fails, delete `token.json` and re-run `node src/auth.js`.

**OAuth consent screen warning** → Add your Google account as a "Test user" in the OAuth consent screen settings.