Vikunja MCP Server – MCP for Vikunja Task Management

An MCP server for Vikunja task management and project management. It connects AI assistants and other Model Context Protocol clients to Vikunja 2.6+ through the stable /api/v2 API.

Version 1.0.0 is tested with Qwen 3.8 27B for reliable MCP tool selection. The server remains model-independent and works with any standards-compliant MCP client.

Features

• 51 focused MCP tools with consistent plural resource names
• Tasks, projects, labels, comments, assignees, relations, and bulk updates
• Saved filters, notifications, project views, and kanban buckets
• Server-side search, filtering, sorting, expansion, and pagination
• Structured JSON results plus readable text for broad client compatibility
• Destructive task, project, label, and notification deletion disabled by default
• Vikunja API v2 contract validation and TypeScript input validation

Requirements

• Node.js 20.18.1 or newer
• Vikunja 2.6.0 or newer
• A Vikunja API token with the permissions needed for the tools you use

Create a token in Vikunja under Settings → API Tokens. Prefer the narrowest permissions that cover your workflow.

Install and configure

The package can run directly through npx:

{
  "mcpServers": {
    "vikunja": {
      "command": "npx",
      "args": ["-y", "@aimbitgmbh/[email protected]"],
      "env": {
        "VIKUNJA_URL": "https://vikunja.example.com",
        "VIKUNJA_API_TOKEN": "your-api-token"
      }
    }
  }
}

VIKUNJA_URL may be the instance root, /api/v1, or /api/v2; the server normalizes it to /api/v2.

To install it globally instead:

npm install --global @aimbitgmbh/[email protected]
vikunja-mcp

Configuration

Use VERIFY_SSL=false only for a trusted development instance with a self-signed certificate.

Available MCP tools

The API uses predictable {resource}_{action} names:

• Tasks: tasks_list, tasks_get, tasks_create, tasks_update, tasks_complete, tasks_delete, tasks_bulk_update
• Projects: projects_list, projects_get, projects_create, projects_update, projects_archive, projects_delete, projects_duplicate
• Labels: labels_list, labels_get, labels_create, labels_update, labels_delete, task_labels_add, task_labels_remove, task_labels_replace
• Collaboration: task_comments_*, task_assignees_*, and task_relations_*
• Advanced: saved_filters_*, notifications_*, project_views_*, and view_buckets_*
• Server: vikunja_info

List tools return pagination metadata. Update tools are partial updates, so clients only need to send changed fields. Progress is exposed as progressPercent from 0 to 100 and converted to Vikunja's fractional representation.

Safety

Permanent deletions return an MCP error until their matching ENABLE_*_DELETE flag is explicitly set to true. Archiving a project and completing a task remain available as safer alternatives. Relation removal and detaching labels or assignees do not delete the related objects themselves.

Upgrading from 0.1.x

Version 1.0.0 targets Vikunja API v2 and intentionally removes API v1 compatibility. Tool names are now consistent, including:

Update stored prompts or automations that refer to old tool names. Passing a former /api/v1 URL remains accepted, but requests are sent to /api/v2.

Vikunja 2.6 does not expose subscription endpoints through its API-token permission registry, so 1.0.0 does not advertise subscription write tools that would fail for the documented API-token setup. Current subscription state remains visible in task and project detail results.

Development

npm ci
cp .env.example .env
npm run check
npm run build

Additional opt-in checks:

• npm run test:live runs a CRUD smoke test against a configured Vikunja instance and removes only records it created.
• npm run test:qwen evaluates tool selection through an OpenAI-compatible endpoint using LLM_BASE_URL, LLM_API_KEY, and LLM_MODEL.

The sanitized Vikunja 2.6 API contract is included for reproducible endpoint checks.

Links

• npm package
• GitHub repository
• Issue tracker
• Vikunja
• Model Context Protocol

MIT © aimbit GmbH