nextcloud-tasks-mcp

An MCP server for Nextcloud Tasks, designed to workas 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 pluginsrequired. Built with FastMCP; authentication uses GitHub OAuthvia FastMCP's OAuth proxy, which satisfies claude.ai's dynamic-client-registration flowwhile 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 returncandidates so the model can retry with a UID. Tools without task_list target yourdefault 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 viaNC_APP_PASSWORD_FILE).

2. GitHub OAuth app (connector authentication)

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

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

Leaving GITHUB_CLIENT_ID/GITHUB_CLIENT_SECRET unset runs the serverunauthenticated — anyone who can reach it can read and write your tasks. Only dothat 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 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: Claudebrokers all connector traffic — including Claude Desktop's — through Anthropic'sservers. 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 haveto reconnect in Claude.

5. Verify with MCP Inspector

npx @modelcontextprotocol/inspector

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

6. Connect Claude

claude.ai (or Claude Desktop) → Settings → Connectors → Add custom connector.
URL: https://tasks-mcp.example.com/mcp.
Claude discovers the OAuth endpoints and sends you through the GitHub consentflow. Approve, and the tools appear.
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 GETof the consent URL. Browsers and claude.ai routinely prefetch that URL, invalidatingthe token the visible page holds, so submitting the form fails with "Invalid orexpired consent token". external skips that page and delegates consent to GitHub'sown authorization screen, which serves the same purpose here. The client redirect-URIallowlist (locked to claude.ai + localhost by default) prevents the classic risk of aconsent-less flow — an arbitrary dynamically-registered client silently capturing anauthorization code — because codes can only be delivered to Claude's callback or yourown machine. Widen ALLOWED_CLIENT_REDIRECT_URIS deliberately if you add other MCPclients, 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 inALLOWED_GITHUB_USERS (check server logs for denied authenticated GitHub user).
Connector breaks after a redeploy → /data wasn't persisted, or you changedGITHUB_CLIENT_SECRET (the storage encryption key derives from it). Remove andre-add the connector.

Development

uv sync
uv run pytest

License

MIT

nextcloud-tasks-mcp