# google-tasks-mcp

An MCP server for [Google Tasks](https://developers.google.com/tasks), in a single
file with **no third-party dependencies** — Node's built-in modules only.

Tasks created here show up in Google Calendar, so it pairs well with a calendar MCP
server: dated events go to the calendar, things you tick off go to Tasks.

## Why no dependencies

This server holds an OAuth token for your Google account. Every package it pulled in
would be one more thing you'd have to trust with that. The Tasks API is a small REST
API and MCP is JSON-RPC over stdio, so neither needs a library. The whole thing is
about 250 lines you can read in one sitting.

## Setup

**1. Get an OAuth client**

In the [Google Cloud console](https://console.cloud.google.com):

- Create a project and enable the **Google Tasks API**
  (`console.cloud.google.com/apis/library/tasks.googleapis.com`)
- Configure the OAuth consent screen (`/auth/branding`) — app name and support email
  are enough
- Add your own Google account under **Audience → Test users** (`/auth/audience`).
  Skipping this gives you `Error 403: access_denied` later
- Create credentials (`/auth/clients`) with application type **Desktop app**, then
  download the JSON

Save it as `gcp-oauth.keys.json` next to `server.js`, or point
`GOOGLE_OAUTH_CREDENTIALS` at it.

**2. Sign in once**

```bash
node server.js auth
```

A browser opens; sign in and approve. The refresh token is written to `tokens.json`
beside the server. Nothing is sent anywhere else.

**3. Register the server**

```json
{
  "mcpServers": {
    "google-tasks": {
      "command": "node",
      "args": ["/absolute/path/to/server.js"]
    }
  }
}
```

Restart your MCP client.

## Tools

| Tool | What it does |
|---|---|
| `list-task-lists` | List task lists |
| `list-tasks` | List tasks in a list, optionally including completed ones |
| `create-task` | Create a task — title, notes, due date, optional parent for a subtask |
| `update-task` | Change title, notes, due date, or completion status |
| `delete-task` | Delete a task permanently |
| `create-task-list` | Create a new task list |

Omit `tasklist` on any call to use `@default`.

## Notes

- **Due dates are date-only.** Google Tasks stores a timestamp but ignores the time
  part, so pass `YYYY-MM-DD` and don't expect a task to fire at a specific hour.
- **While the consent screen is in Testing, authorization expires after 7 days** and
  the refresh token dies with it. Re-run `node server.js auth`. Publishing the app
  removes the limit but requires a homepage and a privacy policy URL, which is
  usually not worth it for personal use.
- The requested scope is `.../auth/tasks` and nothing else.
- The OAuth loopback listens on port 3501; override with `GOOGLE_TASKS_MCP_PORT`.

## Security

`tokens.json` holds a refresh token for your account. It is gitignored — keep it that
way, and treat it like a password. `gcp-oauth.keys.json` contains your OAuth client
secret and is gitignored for the same reason.

## License

MIT