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_*, andtask_relations_* - Advanced:
saved_filters_*,notifications_*,project_views_*, andview_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:liveruns a CRUD smoke test against a configured Vikunja instance and removes only records it created.npm run test:qwenevaluates tool selection through an OpenAI-compatible endpoint usingLLM_BASE_URL,LLM_API_KEY, andLLM_MODEL.
The sanitized Vikunja 2.6 API contract is included for reproducible endpoint checks.
Links
MIT © aimbit GmbH
