vikunja-mcp

An MCP server that bridges Claude (or any MCP client) to a self-hosted Vikunja instance. Exposes projects, tasks, labels, and comments as tools the model can call over stdio.

Requirements

• Node.js >= 18
• A Vikunja instance and an API token

Install

npm install
npm run build

Configuration

The server reads its config from environment variables, falling back to a dotenv-style file (default ~/.vikunja-env, override with VIKUNJA_ENV_FILE).

Variable	Required	Default	Description
VIKUNJA_API_TOKEN	yes	—	Vikunja API token (also accepts API_TOKEN in the env file)
VIKUNJA_SERVICE_URL	yes	—	Base URL of the Vikunja API (also accepts SERVICE_URL)
VIKUNJA_DEFAULT_PROJECT_ID	no	1	Project used when none is specified
VIKUNJA_ENV_FILE	no	~/.vikunja-env	Path to the env file

Example ~/.vikunja-env:

VIKUNJA_API_TOKEN=tk_xxxxxxxxxxxxxxxx
VIKUNJA_SERVICE_URL=https://vikunja.example.com/api/v1
VIKUNJA_DEFAULT_PROJECT_ID=1

Note: Never commit your token. Keep it in ~/.vikunja-env or your MCP client's env config — both are outside the repo.

Usage with Claude

Add to your MCP client config (e.g. Claude Desktop claude_desktop_config.json):

{
  "mcpServers": {
    "vikunja": {
      "command": "node",
      "args": ["/absolute/path/to/vikunja-mcp/dist/index.js"],
      "env": {
        "VIKUNJA_API_TOKEN": "tk_xxxxxxxxxxxxxxxx",
        "VIKUNJA_SERVICE_URL": "https://vikunja.example.com/api/v1"
      }
    }
  }
}

Tools

Diagnostics: check_connection, debug_defaults

Projects: list_projects, get_project, create_project, update_project, archive_project

Tasks: get_tasks, get_task, create_task, update_task, complete_task, delete_task, plan_tasks_for_today

Labels: list_labels, create_label, add_label_to_task, remove_label_from_task

Comments: list_comments, create_comment, delete_comment

Development

npm run dev        # tsup watch build
npm run typecheck  # tsc --noEmit
npm run build      # production build to dist/

License

MIT — see LICENSE.