@shichao402/vikunja-mcp

English | 简体中文

A Vikunja MCP server you can start directly with npx, using stdio transport for Claude Desktop, Cursor, Cherry Studio, and any other MCP-compatible client.

The current package exposes two layers:

• 19 ergonomic tools for day-to-day project, task, label, and comment workflows
• 161 raw REST tools generated from the bundled Vikunja Swagger snapshot, covering every documented operation in that snapshot

That means the package currently exposes 180 MCP tools in total. Raw tools use compact names shaped as vk_<method>_<resource>_<hash12>; each tool description still includes the exact REST operation so the model can call any Vikunja API endpoint precisely when needed.

Installation

No global install is required. The recommended distribution path is npx:

npx -y @shichao402/vikunja-mcp

Environment Variables

You must at least provide the Vikunja base URL:

VIKUNJA_BASE_URL=https://vikunja.example.com

API token authentication is the preferred option:

VIKUNJA_API_TOKEN=your_token

Supported environment variables:

VIKUNJA_BASE_URL=https://vikunja.example.com
VIKUNJA_API_TOKEN=your_api_token

# Optional alias
VIKUNJA_URL=https://vikunja.example.com

# Optional username/password login for self-hosted Vikunja
VIKUNJA_USERNAME=your_username
VIKUNJA_PASSWORD=your_password
VIKUNJA_TOTP_PASSCODE=123456
VIKUNJA_LONG_TOKEN=true

Notes:

• VIKUNJA_API_TOKEN works for both Vikunja Cloud and self-hosted instances and has the highest priority.
• VIKUNJA_USERNAME and VIKUNJA_PASSWORD are intended for self-hosted instances. The server will call /api/v1/login, cache the JWT, and reuse it.
• If you pass a URL ending in /api/v1, the server normalizes it automatically.

Claude Desktop Example

{
  "mcpServers": {
    "vikunja": {
      "command": "npx",
      "args": ["-y", "@shichao402/vikunja-mcp"],
      "env": {
        "VIKUNJA_BASE_URL": "https://vikunja.example.com",
        "VIKUNJA_API_TOKEN": "your_api_token"
      }
    }
  }
}

Tool Layers

Ergonomic tools:

• vikunja_get_server_info
• vikunja_get_current_user
• vikunja_list_projects
• vikunja_get_project
• vikunja_create_project
• vikunja_update_project
• vikunja_delete_project
• vikunja_list_tasks
• vikunja_get_task
• vikunja_create_task
• vikunja_update_task
• vikunja_delete_task
• vikunja_list_labels
• vikunja_create_label
• vikunja_list_task_labels
• vikunja_add_label_to_task
• vikunja_remove_label_from_task
• vikunja_list_task_comments
• vikunja_create_task_comment

Raw tools:

• One raw tool for each of the 161 operations in the bundled Vikunja Swagger snapshot
• Compact generated names, for example vk_put_filters_dac0a4e19aa2, vk_post_tasks_2ca74cd58ce3, vk_put_projects_18c03cfa3b5a, vk_put_tasks_25d391326d4f
• Path and query parameters are top-level fields
• JSON request payloads go in body
• Multipart uploads go in form
• File values inside form use { "filename": "a.txt", "contentBase64": "...", "contentType": "text/plain" }
• Binary download endpoints return { kind, contentType, filename, contentBase64, size }

API Coverage

Full coverage details and remaining limitations are tracked in English coverage docs and 中文覆盖文档.

Current status:

• Swagger operations in the bundled snapshot: 161
• Raw MCP coverage: 161 / 161
• Additional ergonomic tools: 19
• POST /login is exposed both as a raw tool and as an internal self-hosted login capability

Testing

Contract tests:

npm test

Live smoke tests against a real Vikunja instance:

VIKUNJA_LIVE_BASE_URL=http://127.0.0.1:34560 \
VIKUNJA_LIVE_USERNAME=mcpadmin \
VIKUNJA_LIVE_PASSWORD='StrongPass123!' \
npm run test:live

Local Development

npm install
npm run build

Show help:

node dist/index.js --help

Publishing

The package is intentionally distributed via npx because that is the lowest-friction path for MCP clients.

Publishing is automated through GitHub Actions, not local npm publish:

1. Update package.json, package-lock.json, and CHANGELOG.md for the new version.
2. Commit the release metadata, for example chore: release v0.5.0.
3. Create and push a matching v* tag, for example v0.5.0.
4. The Publish to npm workflow publishes to npm via trusted publishing/OIDC.

The workflow verifies that the pushed tag version matches package.json before publishing.

GitHub repository: https://github.com/shichao402/vikunja-mcp