Overview
What is vikunja-mcp?
vikunja-mcp is an MCP (Model Context Protocol) server that integrates with a Vikunja instance and uses multi-tier AI (Claude and OpenAI) to provide intelligent, context‑aware task recommendations optimized for ADHD workflows. It is designed for ADHD users and productivity enthusiasts who want to reduce decision paralysis and align tasks with their current cognitive state.
How to use vikunja-mcp?
Clone the repository, run make build-mcp, and set the environment variables VIKUNJA_URL, VIKUNJA_TOKEN, and OPENAI_API_KEY. Start the server with ./bin/mcp. Then, through a Claude client, you can invoke MCP tools such as daily-focus, get-focus-recommendation, get-task-metadata, and upsert_task to manage tasks and get recommendations.
Key features of vikunja-mcp
- Energy‑aware task selection (low/medium/high/social energy states)
- Mode optimization: deep work, quick tasks, or admin focus
- Time‑constrained planning respecting session duration (5–480 minutes)
- Hyperfocus scoring (1–5 compatibility scale)
- Seamless JSON metadata embedding in Vikunja task descriptions
- Production‑ready: retry logic, structured logging, stateless scaling
- ADHD‑optimised 25‑minute Pomodoro base units with intelligent extension
Use cases of vikunja-mcp
- Creating a new task with embedded hyperfocus metadata for later recommendation
- Getting a daily list of five tasks optimised for a high‑energy, deep‑work session
- Receiving a single best recommendation with explanatory reasoning for a 45‑minute quick‑task block
- Extracting and validating hyperfocus metadata from an existing Vikunja task
FAQ from vikunja-mcp
What makes vikunja-mcp different from standard task managers?
It uses a multi‑tier AI architecture (Claude → MCP → OpenAI → Vikunja) to recommend tasks based on your current energy level, focus mode, and available time—designed specifically to reduce decision paralysis for ADHD users.
What are the runtime dependencies?
Go 1.23.5 or higher, a running Vikunja instance with an API token, an OpenAI API key, and a Claude host (e.g., Claude Desktop) that supports MCP.
Where does my task data live?
All task data remains in your Vikunja instance. vikunja-mcp embeds additional metadata (energy, mode, duration, hyperfocus score) as JSON in the task description without modifying existing content.
Are there any known limits?
The server supports 1000+ tasks with pagination. CRUD operations respond in under 1 second; AI recommendations take 2–3 seconds. It is stateless and scales horizontally for 100+ concurrent users.
Which transport and authentication does it use?
The server communicates via the MCP protocol using a Vikunja API token for task operations and an OpenAI API key for the decision engine. Authentication to Vikunja is handled through the provided API token.
