rmc-vikunja-mcp

A Model Context Protocol (MCP) server that connects LLM-based assistants to the Vikunja task-management platform.

Features

Key design decisions

• Read-Modify-Write for task updates – Vikunja's POST /tasks/{id} endpoint resets fields absent from the request body. update_task therefore fetches the current state, merges the caller's changes, strips read-only timestamps, and posts the result back.
• extra="ignore" on Pydantic models – Unknown fields returned by future API versions are silently discarded instead of causing validation failures.

Quick start

Prerequisites

• Python ≥ 3.14
• uv (recommended) or pip
• A running Vikunja instance with an API token

Configuration

Create a .env file (or export the variables directly):

VIKUNJA_URL=https://your-vikunja-instance.example.com
VIKUNJA_TOKEN=your-api-token

Running the server

You can run the server directly without manual installation using uvx (recommended):

uvx rmc-vikunja-mcp

Alternatively, you can install it via pip and run it using the CLI entry-point:

uv pip install rmc-vikunja-mcp
vikunja-mcp
# or
python -m vikunja_mcp

MCP client configuration (e.g. Claude Desktop)

Using uvx (Recommended)

This method does not require prior installation:

{
  "mcpServers": {
    "vikunja": {
      "command": "uvx",
      "args": [
        "rmc-vikunja-mcp"
      ],
      "env": {
        "VIKUNJA_URL": "https://your-vikunja-instance.example.com",
        "VIKUNJA_TOKEN": "your-api-token"
      }
    }
  }
}

Using globally installed package

If you installed the package via pip or uv pip install:

{
  "mcpServers": {
    "vikunja": {
      "command": "vikunja-mcp",
      "env": {
        "VIKUNJA_URL": "https://your-vikunja-instance.example.com",
        "VIKUNJA_TOKEN": "your-api-token"
      }
    }
  }
}

Development

# Clone and install dev dependencies
git clone https://github.com/rmc8/rmc_vikunja_mcp.git
cd rmc_vikunja_mcp
uv sync

# Run checks
uv run ruff check          # linter
uv run mypy src tests      # type checker (strict mode)
uv run pytest -v           # tests

License

MIT