Vikunja FastMCP V2

Clean-room Vikunja /api/v2 only Model Context Protocol server. Direct Node 24 LTS fetch, runtime deps: @modelcontextprotocol/sdk and zod.

Project History

This repository originally began as a fork of an earlier Vikunja MCP project for evaluation and experimentation. The current v2 product was subsequently rebuilt from scratch against Vikunja's documented /api/v2 contract. No source code, runtime modules, generated output, dependencies, or compatibility wrappers from the original implementation remain in the current tree.

Requirements

• Node.js 24 LTS+
• Vikunja API token with access to the projects you need

Install

Install the prebuilt public release globally:

npm install -g vikunja-fastmcp

Restart the MCP client after installing or updating so it starts the new process.

Optional Agent Skill

The npm package includes a neutral vikunja-fastmcp skill containing the scope, task-identity, pagination, write-safety, attachment, and error rules an agent needs. self_check.agentSkillPath reports its installed location.

Install it for Codex on Windows PowerShell:

$source = Join-Path (npm root -g) "vikunja-fastmcp\skills\vikunja-fastmcp"
$target = Join-Path $HOME ".codex\skills\vikunja-fastmcp"
New-Item -ItemType Directory -Force -Path (Split-Path $target) | Out-Null
Copy-Item -LiteralPath $source -Destination $target -Recurse -Force

For Claude, use $HOME\.claude\skills\vikunja-fastmcp as the target. For an agent without skill-folder support, place the contents of SKILL.md in that client's persistent agent instructions or rules file. Restart the agent after installing or updating the skill.

Environment

| Variable | Required | Description | | --- | --- | --- | | VIKUNJA_URL | yes | Server root or …/api/v2 (e.g. http://host:3456) | | VIKUNJA_API_TOKEN | yes | Bearer token (tk_…) | | VIKUNJA_WEB_URL | no | Browser base for task/project links | | VIKUNJA_ATTACHMENT_DOWNLOAD_ROOT | no | Sandboxed download root (defaults under the OS temp directory) | | VIKUNJA_MAX_ATTACHMENT_BYTES | no | Upload/download size ceiling (default 100 MiB) | | VIKUNJA_TEMPLATE_FILE | no | Machine-local template JSON path (defaults under the user home directory) |

Never commit tokens. Rejects /api/v1 URLs.

Configure

{
  "mcpServers": {
    "vikunja": {
      "command": "vikunja-mcp",
      "args": [],
      "env": {
        "VIKUNJA_URL": "https://vikunja.example.com/api/v2",
        "VIKUNJA_API_TOKEN": "<YOUR_TOKEN>"
      }
    }
  }
}

Create an API token in Vikunja under Settings -> API Tokens. Use the /api/v2 URL for your own Vikunja server. Store the token only in local MCP configuration or a secret store.

Local Development

npm install
npm run build
node dist/index.js

MCP clients should launch dist/index.js over stdio with the env vars above.

Emergency Python Fallback

The supported path is the npm-installed MCP. For a one-time emergency where the MCP cannot start, fallback/vikunja-cli.py provides a standalone /api/v2 CLI with explicit setup, safety limits, and offline unit tests documented in fallback/README.md. Do not run both as independent tracker writers.

Tools

• self_check / vikunja_auth — diagnostics and current user (no email)
• vikunja_projects — list / get
• vikunja_tasks — CRUD, list (default open only), create_if_absent, assignees, labels, relations, attachments
• vikunja_task_comments
• vikunja_labels — global labels (title or id)
• vikunja_users
• vikunja_teams — teams/members (userId is the Vikunja user id)
• vikunja_filters — create/get/update/delete (no list; API has no collection GET)
• vikunja_task_bulk — native bulk update; bounded composed create/delete
• vikunja_task_reminders — list/add/remove task reminders
• vikunja_batch_import — detect/preview/import/status for native CSV migration
• vikunja_export_project — local JSON/CSV task export
• vikunja_request_user_export / vikunja_download_user_export
• vikunja_templates — machine-local templates and task instantiation
• vikunja_webhooks — project/user webhooks and event discovery

Templates default to ~/.vikunja-fastmcp/templates.json and may be relocated with VIKUNJA_TEMPLATE_FILE. Downloads and exports remain inside VIKUNJA_ATTACHMENT_DOWNLOAD_ROOT. Composed batch create/delete operations are bounded to 100 tasks and are not atomic.

Vikunja permissions still apply per operation. Applying a label may be denied even when ordinary task updates are allowed. Some Vikunja builds also require JWT/local-password authentication for user-data export routes; the MCP preserves the real 401 instead of presenting false JWT advice.

See generated MCP_API.md for inputs. Responses are Markdown summary + one JSON envelope (ok / error). Task lists default to 25 items and cap each project page at 100; use countOnly for totals and pagination for larger result sets.

Operational Limits

• Bulk update/close: 100 global task IDs per call.
• Bulk create: 100 tasks per call; composed and non-atomic.
• Bulk delete: 100 task IDs per call; composed, non-atomic, and requires confirm: true.
• CSV import and file transfer: 100 MiB by default through VIKUNJA_MAX_ATTACHMENT_BYTES; Vikunja controls CSV row limits.
• Multi-project lists page each project independently. Prefer countOnly when only totals are needed.

Develop

npm test
npm run typecheck
npm run docs:api
npm run docs:api:check

License

MIT — see LICENSE and AUTHORS.md.