nextcloud-tasks-mcp

An MCP server for Nextcloud Tasks, designed to work as a claude.ai / Claude Desktop custom connector — 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; 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

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).

Related MCP server: Google Tasks MCP Server

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

4. Run it

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

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:

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

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

uv sync
uv run pytest

License

MIT