vikunja-mcp

A remote MCP (Model Context Protocol) server that connects Claude to your self-hosted Vikunja instance. Add it as a custom connector in Claude.ai and manage your tasks conversationally.

Available tools

Quick start

npm install
npm run build

export VIKUNJA_URL=https://your-vikunja-instance.example.com
export VIKUNJA_TOKEN=your-api-token
export MCP_AUTH_TOKEN=$(openssl rand -hex 32)
export PORT=9090

node build/index.js

Then add your server as a custom connector in Claude.ai under Settings > Connectors:

https://your-server.example.com/mcp?token=<MCP_AUTH_TOKEN>

See DEPLOY-UBERSPACE.md for a full deployment walkthrough on Uberspace.

Configuration

Auth

When MCP_AUTH_TOKEN is set, the server rejects any request to /mcp that does not include a matching ?token=… query parameter with a 401 Unauthorized response.

Generate a strong token:

openssl rand -hex 32

Add it to the connector URL in Claude.ai:

https://your-server.example.com/mcp?token=<your-token>

If MCP_AUTH_TOKEN is left unset the endpoint is open to anyone who can reach it — only do this on a private, firewalled network.

Calendar integration

The get_calendar_events tool reads events from any number of .ics sources and returns them grouped by day. When configured, weekly_review also shows a THIS WEEK'S CALENDAR section so your schedule and task backlog are reviewed together.

Posteo users: your webcal subscription URL is under Calendar Settings → iCal subscription. Add it to CALENDAR_ICS_URLS — no sync daemon needed.

export CALENDAR_ICS_URLS=webcal://posteo.de/calendars/you/personal

For multiple calendars, separate with commas:

export CALENDAR_ICS_URLS=webcal://posteo.de/calendars/you/personal,webcal://posteo.de/calendars/you/work

For local .ics files (e.g. synced from CalDAV via vdirsyncer):

export CALENDAR_ICS_FILES=/home/user/calendars/shifts.ics,/home/user/calendars/personal.ics

Both vars are optional. Calendar features are silently disabled when neither is set.

Architecture

• Transport: Streamable HTTP (stateless) — the current MCP standard for remote servers

• Auth: Query-parameter token (MCP_AUTH_TOKEN) for the MCP endpoint; Vikunja API token for upstream API calls

• Runtime: Node.js + Express

• SDK: @modelcontextprotocol/sdk v1.x

Requirements

• Node.js ≥ 18

• A self-hosted Vikunja instance with an API token

• A publicly-accessible URL for Claude.ai to reach the server