Vikunja tasks

emperor-vikunja

An MCP server for [Vikunja](https://vikunja.io), the open-source task manager. Let Claude, kowalski or any MCP client list, read, create and update your tasks, comment on them and see your projects.

Built on emperor-mcp (Emperor Profile P1.1):

• Stateless Streamable HTTP at /mcp, plus stdio for desktop clients.
• Your token is forwarded, never stored. Over HTTP each request brings its own Authorization: Bearer ; the server passes it to Vikunja and forgets it. There are no default or test tokens.
• Framed output. Task text written by people (titles, descriptions, comments) reaches the model marked as messages for the user, never as instructions for the model.
• Read-only unless you say otherwise. Started plain, the server offers only the three read tools; --writable (or VIKUNJA_WRITABLE=true) adds the three that change tasks.
• Six annotated tools with compact definitions, a doctor subcommand, Markdown in and plain text out.
• Clear auth failures. When Vikunja refuses the token, the MCP response over HTTP is a 401 or 403, so the client can ask for a new token.

Tools

Without --writable the write tools are not in the server at all: they are neither listed nor callable, so neither the model nor text it reads can reach them.

Every tool is marked open-world (it talks to a Vikunja that other people change). update_task is marked destructive because a new title or description replaces the old text, which Vikunja does not keep, and labels and assignees can be removed; it is idempotent because the same call twice leaves the task as one call did.

Labels are named by title. A label that does not exist is an error unless the call passes create_missing_labels: true, so a typo does not quietly add a new label. Assignees are usernames (exact, case-insensitive; a leading @ is fine). Names are checked before anything is written: a bad label or username leaves no half-made task.

Priority: 0 unset, 1 low, 2 medium, 3 high, 4 urgent, 5 do now. Dates: YYYY-MM-DD (read as 00:00 UTC) or ISO-8601; dates come back as RFC 3339, or null when unset.

Descriptions and comments are stored by Vikunja as HTML. What the model writes in Markdown is rendered to HTML on the way in (raw HTML in the Markdown is escaped, not passed through); HTML read back is rendered to plain text.

Install

From a release (Linux x86_64, macOS arm64 and x86_64, Windows x86_64): download the archive for your platform from Releases and put emperor-vikunja on your PATH.

From source (Rust 1.88 or newer):

cargo install --git https://github.com/yarenty/emperor-vikunja

Get a token

In Vikunja open Settings > API Tokens > Create a token, pick an expiry date and tick these permissions (the minimum the six tools need with --writable):

The server is read-only by default; for a read-only assistant give it a token with only the read_all / read_one permissions (and other: user for doctor).

Run

Local (stdio)

export VIKUNJA_TOKEN=...            # from Settings > API Tokens

emperor-vikunja serve --stdio --base-url https://vikunja.example.com # read-only emperor-vikunja serve --stdio --base-url https://vikunja.example.com --writable # also create, update, comment

Docker (stdio)

docker build -t emperor-vikunja https://github.com/yarenty/emperor-vikunja.git

docker run -i --rm -e VIKUNJA_URL=https://vikunja.example.com -e VIKUNJA_TOKEN emperor-vikunja

read-only by default; to create, update and comment add -e VIKUNJA_WRITABLE=true

(or --writable after the image name)

The image runs emperor-vikunja serve --stdio as a non-root user; the Vikunja address comes from VIKUNJA_URL.

Shared (HTTP)

# --writable: the users of this server may create, update and comment; leave it out for read-only

emperor-vikunja serve --base-url https://vikunja.example.com --bind 127.0.0.1:8034 --writable

MCP endpoint: http://127.0.0.1:8034/mcp liveness: http://127.0.0.1:8034/health

Every MCP request must carry Authorization: Bearer ; each user brings their own. VIKUNJA_TOKEN is ignored in this mode, so one person's token can never answer another person's request. Tool discovery (tools/list) works without a token.

When Vikunja refuses the token (401) or the token may not do this (403), the MCP response carries that HTTP status (401 with WWW-Authenticate: Bearer error="invalid_token") and a JSON-RPC error with code -32040 and data.httpStatus. Over stdio the client gets the same JSON-RPC error.

Flags and headers

With X-Upstream-Url one server can front several Vikunja instances. The server will then call whichever https host a client names, with that client's token; run it where outbound calls to arbitrary hosts are acceptable, or leave the header out at your proxy and rely on --base-url.

Logs go to stderr; RUST_LOG=debug for more. In production put the HTTP server behind a reverse proxy that terminates TLS (Emperor Profile E5).

Connect

Claude Desktop (claude_desktop_config.json):

--writable lets Claude create, update and comment; drop it for a read-only connection.

{

"mcpServers": { "vikunja": { "command": "emperor-vikunja", "args": ["serve", "--stdio", "--base-url", "https://vikunja.example.com", "--writable"], "env": { "VIKUNJA_TOKEN": " " } } } }

Claude Code:

# stdio, read-only (the default)

claude mcp add vikunja-ro --env VIKUNJA_TOKEN= -- \ emperor-vikunja serve --stdio --base-url https://vikunja.example.com

stdio, --writable: Claude may also create, update and comment

claude mcp add vikunja --env VIKUNJA_TOKEN= -- \ emperor-vikunja serve --stdio --base-url https://vikunja.example.com --writable

or against a running HTTP server (its own --writable decides what is listed)

claude mcp add --transport http vikunja http://127.0.0.1:8034/mcp \ --header "Authorization: Bearer " \ --header "X-Upstream-Url: https://vikunja.example.com"

[kowalski](https://github.com/yarenty/kowalski) (config.toml):

[[mcp.servers]]

name = "vikunja" transport = "stdio"

--writable: the agent may create, update and comment; drop it for read-only.

command = ["emperor-vikunja", "serve", "--stdio", "--base-url", "https://vikunja.example.com", "--writable"]

VIKUNJA_TOKEN is read from kowalski's environment.

or over HTTP (the server's own --writable decides what is listed)

[[mcp.servers]] name = "vikunja-http" transport = "http" url = "http://127.0.0.1:8034/mcp" headers = { Authorization = "Bearer ", X-Upstream-Url = "https://vikunja.example.com" }

Doctor

emperor-vikunja doctor checks the setup before you start the server and exits 1 when something is broken, so scripts and container health checks can use it:

$ VIKUNJA_TOKEN=... emperor-vikunja doctor --base-url https://vikunja.example.com

emperor-vikunja 0.2.0 doctor [ok ] base url https://vikunja.example.com/ [ok ] vikunja api Vikunja v2.7.1 [ok ] VIKUNJA_TOKEN set (43 chars) [ok ] vikunja login token works for user alice [ok ] mode read-only: get_task, list_projects, list_tasks (pass --writable or VIKUNJA_WRITABLE=true for create_task, update_task, comment) [ok ] listen address 127.0.0.1:8034 is free [ok ] tool budget 3 of at most 8 tools all good (0 warning(s))

It checks that the URL parses, GET /api/v1/info answers, the token is set (only its length is shown) and GET /api/v1/user accepts it, which tools the mode serves (three read tools by default, all six with --writable; a warning when the deprecated --read-only is given), the listen address is free (skipped with --stdio), and the tool count is within the emperor-mcp budget. Without VIKUNJA_TOKEN in HTTP mode the token line is a warning, because the token comes per request; with --stdio it is a failure. The same goes for --base-url: over HTTP its absence is a warning (requests must send X-Upstream-Url), with --stdio a failure.

Compatibility

Tested against Vikunja v2.7 (the vikunja/vikunja image). Tasks are listed through GET /tasks with