Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Vikunja MCP Server what tasks are due this week?"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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.
Tool | Description |
| List all projects |
| Get project details |
| Create a new project |
| Update a project |
| Delete a project |
| List/filter/search tasks across all projects |
| Get task details including comments |
| Create a task in a project |
| Update task properties |
| Delete a task |
| Mark a task as done |
| Mark a task as not done |
| Add a comment to a task |
| List all labels |
| Create a new label |
| Attach a label to a task |
| Remove a label from a task |
| Generate a weekly review summary |
| Agenda view of tasks with due dates (overdue + upcoming) |
| Link two tasks (subtask, blocking, precedes, related, …) |
| Remove a relation between two tasks |
| Update multiple tasks at once (priority, status, dates, …) |
| Get all notifications with unread count |
| Save a named filter for reuse |
| Get a saved filter by ID |
| Update a saved filter |
| Delete a saved filter |
| Events from configured .ics files and webcal feeds, grouped by day |
Related MCP server: vikunja-mcp
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.jsThen 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.
Variable | Required | Description |
| Yes | Base URL of your Vikunja instance (no trailing slash) |
| Yes | API token from Vikunja Settings > API Tokens |
| Recommended | Shared secret for the |
| No | Port to listen on (default: |
| No | Comma-separated paths to local |
| No | Comma-separated webcal/https iCal subscription URLs |
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 32Add 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.
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/personalFor multiple calendars, separate with commas:
export CALENDAR_ICS_URLS=webcal://posteo.de/calendars/you/personal,webcal://posteo.de/calendars/you/workFor local .ics files (e.g. synced from CalDAV via vdirsyncer):
export CALENDAR_ICS_FILES=/home/user/calendars/shifts.ics,/home/user/calendars/personal.icsBoth vars are optional. Calendar features are silently disabled when neither is set.
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
Node.js ≥ 18
A self-hosted Vikunja instance with an API token
A publicly-accessible URL for Claude.ai to reach the server
This server cannot be deployed
Persistent context for Claude. Your AI always knows your projects and next actions across sessions.
Connect Claude to your Platform7n workspaces — chat, links, and tasks. One-click OAuth.
Personal CRM for Claude. Contacts live as plain-text files in your own Google Drive.
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
