Vikunja MCP Server

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