vikunja-mcp

An MCP server for Vikunja task management, designed to work as a claude.ai / Claude Desktop custom connector — so Claude can view, add, complete, edit, and delete your tasks from the web or desktop app.

Talks to Vikunja's REST API with a personal API token. Targets Vikunja v0.24+ / v2.x (task listing via project views; updates send the full task object so nothing gets zeroed). Built with FastMCP; authentication uses GitHub OAuth via FastMCP's OAuth proxy, restricted to an allowlist of GitHub usernames.

Tools

Tasks are matched by numeric id or title substring; ambiguous matches return candidates so the model can retry with an id. Tools without project target your default project (VIKUNJA_DEFAULT_PROJECT, falling back to Inbox, then the first project). Priority uses Vikunja's scale: 1 low → 5 DO NOW (higher = more urgent).

Related MCP server: Vikunja MCP Server

Setup

1. Vikunja API token

In Vikunja: Settings → API Tokens → Create a token. Grant it read/write on Projects and Tasks (add other scopes only if you extend the server). The token goes in VIKUNJA_API_TOKEN (or a secret file via VIKUNJA_API_TOKEN_FILE).

2. GitHub OAuth app (connector authentication)

1. https://github.com/settings/developers → OAuth Apps → New OAuth App.

2. Authorization callback URL: https://vikunja-mcp.example.com/auth/callback (your MCP_BASE_URL + /auth/callback).

3. Register, generate a client secret, and set GITHUB_CLIENT_ID / GITHUB_CLIENT_SECRET / ALLOWED_GITHUB_USERS.

Leaving the client ID/secret unset runs the server unauthenticated — local testing only.

3. Configuration reference

4. Run it

See compose.example.yml. Expose it publicly at MCP_BASE_URL through your reverse proxy; optionally restrict ingress to Anthropic's egress range (160.79.104.0/21). Persist /data or connected clients must re-authorize after every restart.

5. Verify, then connect Claude

npx @modelcontextprotocol/inspector   # → https://vikunja-mcp.example.com/mcp

Then claude.ai (or Claude Desktop) → Settings → Connectors → Add custom connector with the same URL. You'll land on GitHub's authorize page; 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 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. The client redirect-URI allowlist (claude.ai + localhost by default) prevents the classic risk of a consent-less flow — an arbitrary dynamically-registered client silently capturing an authorization code.

Failure modes

• 401 from Vikunja → the API token is wrong, expired, or revoked; create a new one.

• 403 from Vikunja → the token is missing a scope for that operation — recreate it with Projects + Tasks read/write.

• GitHub login succeeds but tools are denied → your login isn't in ALLOWED_GITHUB_USERS (check logs for denied authenticated GitHub user).

• Connector breaks after a redeploy → /data wasn't persisted, or the GitHub client secret changed (registration storage is keyed to it). Re-add the connector.

Development

uv sync
uv run pytest

License

MIT