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

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