# nextcloud-tasks-mcp

An [MCP](https://modelcontextprotocol.io) server for **Nextcloud Tasks**, designed to work
as a [claude.ai / Claude Desktop custom connector](https://support.claude.com/en/articles/11175166)
— so Claude can view, add, complete, edit, and delete your todos from the web or desktop app.

Talks CalDAV (VTODO) directly to your Nextcloud with an app password. No Nextcloud plugins
required. Built with [FastMCP](https://gofastmcp.com); authentication uses GitHub OAuth
via FastMCP's OAuth proxy, which satisfies claude.ai's dynamic-client-registration flow
while restricting access to an allowlist of GitHub usernames.

## Tools

| Tool | Description |
|---|---|
| `list_task_lists` | Show task lists; marks the default |
| `create_task_list` | Create a new list |
| `list_tasks` | Open tasks (or all with `include_completed`), with subtask relations |
| `get_task` | Full detail for one task, including notes |
| `add_task` | Add a task — due date, priority, notes, parent (subtask) |
| `complete_task` / `reopen_task` | Toggle completion |
| `edit_task` | Change summary / due / priority / notes |
| `delete_task` | Permanent delete; requires `confirm=true` |

Tasks are matched by UID, UID prefix, or summary substring; ambiguous matches return
candidates so the model can retry with a UID. Tools without `task_list` target your
default list (`NC_TASKS_DEFAULT_LIST`, falling back to `tasks`, then the first list).

## Setup

### 1. Nextcloud app password

In Nextcloud: **Settings → Security → Devices & sessions → Create new app password**.
Note the generated password; it goes in `NC_APP_PASSWORD` (or a secret file via
`NC_APP_PASSWORD_FILE`).

### 2. GitHub OAuth app (connector authentication)

The server sits on the public internet (claude.ai must reach it), so it fronts itself
with GitHub OAuth: connecting a Claude client pops a GitHub login, and only the GitHub
accounts you allowlist get through.

1. Go to <https://github.com/settings/developers> → **OAuth Apps → New OAuth App**.
2. **Application name**: anything (e.g. `nextcloud-tasks-mcp`).
3. **Homepage URL**: your server URL, e.g. `https://tasks-mcp.example.com`.
4. **Authorization callback URL**: `https://tasks-mcp.example.com/auth/callback`
   (your `MCP_BASE_URL` + `/auth/callback` — must match exactly).
5. Register, then **Generate a new client secret**. The client ID and secret go in
   `GITHUB_CLIENT_ID` / `GITHUB_CLIENT_SECRET`.
6. Set `ALLOWED_GITHUB_USERS` to your GitHub username (comma-separate several).

Leaving `GITHUB_CLIENT_ID`/`GITHUB_CLIENT_SECRET` unset runs the server
**unauthenticated** — anyone who can reach it can read and write your tasks. Only do
that for local testing.

### 3. Configuration reference

| Variable | Required | Description |
|---|---|---|
| `NC_URL` | yes | Nextcloud base URL, e.g. `https://cloud.example.com` |
| `NC_USER` | yes | Nextcloud login |
| `NC_APP_PASSWORD` | yes | App password (or `NC_APP_PASSWORD_FILE`) |
| `NC_TASKS_DEFAULT_LIST` | no | Default list slug/name (default `tasks`) |
| `MCP_BASE_URL` | with auth | Public URL of this server |
| `GITHUB_CLIENT_ID` | with auth | OAuth app client ID (or `_FILE`) |
| `GITHUB_CLIENT_SECRET` | with auth | OAuth app client secret (or `_FILE`) |
| `ALLOWED_GITHUB_USERS` | with auth | Comma-separated GitHub logins allowed in |
| `CONSENT_MODE` | no | `external` (default), `true`, `remember`, or `false` — see below |
| `ALLOWED_CLIENT_REDIRECT_URIS` | no | Redirect-URI patterns MCP clients may register (default: `https://claude.ai/api/mcp/auth_callback,http://localhost:*,http://127.0.0.1:*`) |
| `HOST` / `PORT` / `MCP_PATH` | no | Bind address (`0.0.0.0`), port (`8000`), path (`/mcp`) |
| `FASTMCP_HOME` | no | Where OAuth client registrations persist (`/data` in Docker) |

### 4. Run it

Docker (see [`compose.example.yml`](compose.example.yml) for the full example with secrets):

```bash
docker run -d --name tasks-mcp -p 8000:8000 \
  -e NC_URL=https://cloud.example.com \
  -e NC_USER=me -e NC_APP_PASSWORD=xxxxx-xxxxx-xxxxx-xxxxx-xxxxx \
  -e MCP_BASE_URL=https://tasks-mcp.example.com \
  -e GITHUB_CLIENT_ID=Ov23li... -e GITHUB_CLIENT_SECRET=... \
  -e ALLOWED_GITHUB_USERS=your-github-username \
  -v tasks-mcp-data:/data \
  ghcr.io/crosbyh/nextcloud-tasks-mcp:latest
```

Or without Docker:

```bash
uv tool install nextcloud-tasks-mcp   # or: pip install .
NC_URL=... NC_USER=... NC_APP_PASSWORD=... nextcloud-tasks-mcp
```

Expose it publicly at `MCP_BASE_URL` through your reverse proxy (TLS terminated there;
route to container port 8000). It must be reachable from the public internet: Claude
brokers all connector traffic — including Claude Desktop's — through Anthropic's
servers. Optionally restrict ingress to Anthropic's published egress range
(`160.79.104.0/21`) at the proxy for defense in depth.

> **Persist `/data`.** FastMCP stores OAuth client registrations there (encrypted).
> Without a volume, every container restart forgets registered clients and you'll have
> to reconnect in Claude.

### 5. Verify with MCP Inspector

```bash
npx @modelcontextprotocol/inspector
```

Enter `https://tasks-mcp.example.com/mcp` (transport: Streamable HTTP), complete the
GitHub login, and try `list_task_lists`.

### 6. Connect Claude

1. claude.ai (or Claude Desktop) → **Settings → Connectors → Add custom connector**.
2. URL: `https://tasks-mcp.example.com/mcp`.
3. Claude discovers the OAuth endpoints and sends you through the GitHub consent
   flow. Approve, and the tools appear.
4. Ask Claude: *"What's on my task list?"*

### Why `CONSENT_MODE=external` is the default

FastMCP's built-in consent page (as of 3.4.4) regenerates its CSRF token on every GET
of the consent URL. Browsers and claude.ai routinely prefetch that URL, invalidating
the token the visible page holds, so submitting the form fails with **"Invalid or
expired consent token"**. `external` skips that page and delegates consent to GitHub's
own authorization screen, which serves the same purpose here. The client redirect-URI
allowlist (locked to claude.ai + localhost by default) prevents the classic risk of a
consent-less flow — an arbitrary dynamically-registered client silently capturing an
authorization code — because codes can only be delivered to Claude's callback or your
own machine. Widen `ALLOWED_CLIENT_REDIRECT_URIS` deliberately if you add other MCP
clients, and consider `CONSENT_MODE=remember` if you do.

## Failure modes

- **401 from Nextcloud** → the app password is wrong or was revoked; generate a new one.
- **GitHub login succeeds but tools are denied** → your login isn't in
  `ALLOWED_GITHUB_USERS` (check server logs for `denied authenticated GitHub user`).
- **Connector breaks after a redeploy** → `/data` wasn't persisted, or you changed
  `GITHUB_CLIENT_SECRET` (the storage encryption key derives from it). Remove and
  re-add the connector.

## Development

```bash
uv sync
uv run pytest
```

## License

MIT