Vikunja FastMCP V2

Clean-room Vikunja /api/v2 only Model Context Protocol server. It uses Node 24 LTS fetch with only @modelcontextprotocol/sdk and zod as runtime dependencies.

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.

Architecture

The public contract is in docs/V2_API_CONTRACT.md. The implementation roadmap and measured token budgets are in docs/VMCP_IMPLEMENTATION_PLAN.md. The profile, response, ledger, and migration decisions are recorded in docs/ADR-0001-agent-efficient-mcp-contract.md.

Requirements

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

Install

Install the prebuilt public release globally:

npm install -g vikunja-fastmcp@latest

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

Verify on Windows PowerShell:

npm list -g vikunja-fastmcp --depth=0
(Get-Command vikunja-mcp).Source

Verify on macOS or Linux:

npm list -g vikunja-fastmcp --depth=0
command -v vikunja-mcp

Copy-Paste Agent Install Or Update Prompt

Paste this into any MCP-capable agent for a new installation or an update. It does not assume an operating system, agent brand, project, username, or fixed package version.

Install or update the Vikunja MCP server for the current user:
1. Run `npm install -g vikunja-fastmcp@latest`.
2. Verify the package with `npm list -g vikunja-fastmcp --depth=0` and locate
   `vikunja-mcp` using the operating system's command-resolution tool.
3. Keep or create a stdio MCP server named `vikunja` whose command is
   `vikunja-mcp` with no arguments. Never use a checkout, junction, tarball,
   release download, or `dist` path.
4. Preserve existing `VIKUNJA_URL` and `VIKUNJA_API_TOKEN` values without
   printing them. Ask for missing values through a secret-safe input method.
5. Run `npm root -g` and locate the packaged `skills/vikunja-fastmcp` folder.
   If the client supports skills, install it when missing; otherwise refresh
   the existing copy in place. Reuse one user-wide copy and remove no other
   skill unless it is an exact duplicate of this packaged skill.
6. If the client has no skill-folder support, merge `SKILL.md` into its
   persistent agent instructions. Do not create a second conflicting copy.
7. Restart the MCP client. Report the installed package version, resolved
   command path, MCP config path, and active skill path without showing secrets.

Packaged 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 with detail: "full" reports its installed location as agentSkillPath; the default basic check stays compact.

Example PowerShell copy into a client-specific user-wide skill target:

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

Choose the target required by the MCP client. For a client without skill-folder support, place the contents of SKILL.md in its persistent agent instructions. Refresh the same target after every package update instead of accumulating versioned or project-local copies. Restart the client after refreshing it.

Environment

Required: