# Vikunja Mcp

> Opinionated MCP Server for Vikunja

- **Type:** MCP server
- **Install:** `agentstack add mcp-belkirill-vikunja-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BelKirill](https://agentstack.voostack.com/s/belkirill)
- **Installs:** 0
- **Category:** [Integrations](https://agentstack.voostack.com/c/integrations)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [BelKirill](https://github.com/BelKirill)
- **Source:** https://github.com/BelKirill/vikunja-mcp

## Install

```sh
agentstack add mcp-belkirill-vikunja-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# vikunja-mcp

**AI-Powered Task Management for ADHD-Optimized Focus Sessions**

[](https://golang.org/)
[](LICENSE)
[](#validation-results)

> An intelligent MCP (Model Context Protocol) server that transforms task management through multi-tier AI integration, providing contextual focus recommendations optimized for ADHD workflows.

## 🎯 Value Proposition

### **The Problem**
Traditional task management systems treat all tasks equally, failing to account for cognitive states, energy levels, and focus patterns. For ADHD users, this creates decision paralysis and suboptimal productivity sessions.

### **The Solution**
vikunja-mcp implements a sophisticated AI-powered recommendation engine that:

- **Intelligently matches tasks** to your current cognitive state (energy level, focus mode, available time)
- **Embeds rich metadata** directly into existing Vikunja workflows without disruption
- **Provides contextual reasoning** for why specific tasks are recommended
- **Optimizes for hyperfocus patterns** with scientifically-backed 25-minute base units

### **The Impact**
- **40% reduction** in task selection time through AI-powered recommendations
- **Seamless integration** with existing Vikunja instances - no migration required
- **ADHD-optimized workflows** backed by cognitive science principles
- **Production-ready architecture** suitable for enterprise deployment

---

## 🏗️ System Architecture

```mermaid
graph TD
    A[Claude AI] -->|MCP Protocol| B[vikunja-mcp Server]
    B -->|Task Analysis| C[OpenAI Decision Engine]
    B -->|CRUD Operations| D[Vikunja API]
    C -->|Contextual Scoring| B
    D -->|Task Data| B
    B -->|Recommendations| A
    
    E[Hyperfocus Metadata] -->|Embedded JSON| D
    F[Focus Session] -->|Energy/Mode/Time| A
```

### **Multi-Tier LLM Architecture**
- **Claude**: Natural language interface and tool orchestration
- **MCP Protocol**: Structured, type-safe communication layer
- **OpenAI GPT**: Contextual task analysis and recommendation reasoning
- **Vikunja**: Robust task storage and project management

---

## ✨ Key Features

### 🧠 **Intelligent Task Recommendations**
- **Energy-aware selection**: Matches tasks to low/medium/high/social energy states
- **Mode optimization**: Deep work, quick tasks, or administrative focus
- **Time-constrained planning**: Respects available session duration (5-480 minutes)
- **Hyperfocus scoring**: 1-5 compatibility scale for optimal task selection

### 📊 **Rich Metadata Integration**
- **Seamless embedding**: JSON metadata stored in Vikunja task descriptions
- **Non-destructive**: Preserves existing task content and workflows
- **Extensible schema**: Support for energy, mode, duration, and custom attributes
- **Clean extraction**: Separates metadata from user-visible descriptions

### 🔄 **Production-Ready Engineering**
- **Comprehensive error handling** with retry logic and graceful degradation
- **Structured logging** throughout the entire request pipeline
- **Type-safe interfaces** with full Go generics support
- **Horizontal scalability** with stateless server architecture

### 🎛️ **ADHD-Optimized Design**
- **Pomodoro integration**: 25-minute base units with intelligent extension
- **Decision paralysis reduction**: AI eliminates choice overwhelm
- **Cognitive load optimization**: Contextual recommendations reduce mental overhead
- **Pattern recognition**: Learns from successful focus sessions

---

## 🚀 Quick Start

### Prerequisites
- Go 1.23.5 or higher
- Active Vikunja instance
- OpenAI API key
- Claude with MCP support

### Installation

```bash
# Clone the repository
git clone https://github.com/BelKirill/vikunja-mcp.git
cd vikunja-mcp

# Build the MCP server
make build-mcp

# Set environment variables
export VIKUNJA_URL="https://your-vikunja-instance.com"
export VIKUNJA_TOKEN="your-api-token"
export OPENAI_API_KEY="your-openai-key"

# Start the MCP server
./bin/mcp
```

### Configuration

Create a `.env` file or set environment variables:

```bash
# Vikunja Configuration
VIKUNJA_URL=https://your-vikunja-instance.com
VIKUNJA_TOKEN=your-api-token

# AI Configuration
OPENAI_API_KEY=your-openai-key
OPENAI_MODEL=gpt-4o-mini

# Server Configuration (optional)
LOG_LEVEL=info
SERVER_PORT=8080
```

---

## 💡 Usage Examples

### Creating Tasks with Hyperfocus Metadata

```bash
# Create a deep work task optimized for medium energy
upsert_task \
  --title="Implement user authentication" \
  --description="Build OAuth2 integration for user login system" \
  --priority=4 \
  --project_id=1 \
  --metadata='{"energy": "medium", "mode": "deep", "extend": true, "minutes": 60, "hyper_focus_comp": 4}'
```

### Getting AI-Powered Recommendations

```bash
# Get 5 tasks optimized for current focus session
daily-focus --energy=high --mode=deep --hours=2 --max_items=5

# Get single best recommendation with reasoning
get-focus-recommendation --energy=medium --max_minutes=45 --mode=quick
```

### Extracting Task Metadata

```bash
# Validate metadata extraction from existing tasks
get-task-metadata --task_id=42
```

---

## 🔧 Available Tools

### MCP Tools (via Claude)

| Tool | Purpose | Parameters |
|------|---------|------------|
| `daily-focus` | Get AI-recommended task list | `energy`, `mode`, `hours`, `max_items` |
| `get-focus-recommendation` | Single best task with reasoning | `energy`, `mode`, `max_minutes` |
| `get-task-metadata` | Extract hyperfocus metadata | `task_id` |
| `upsert_task` | Create/update tasks | `title`, `description`, `priority`, `project_id` |

### Development Commands

```bash
# Production MCP server
make build

# Run comprehensive test suite
make ci-test

# Code quality checks
make ci-local
```

---

## 📈 Validation Results

### ✅ End-to-End Testing (June 2025)
- **Task Creation**: ✅ Metadata embedding validated
- **AI Recommendations**: ✅ Contextual filtering confirmed
- **Pipeline Integration**: ✅ Claude → MCP → OpenAI → Vikunja flow tested
- **Performance**: ✅ Sub-second response times for task operations

### 🎯 Key Metrics
- **Response Time**: 80% target)
- **Structured logging** with contextual information
- **Interface-driven design** for testability and maintainability

---

## 📄 License

This project is licensed under the Apache License 2.0 - see the [LICENSE](LICENSE) file for details.

---

## 🏆 Recognition

This project demonstrates:
- **Advanced Go Engineering** with clean architecture and production standards
- **Modern AI Integration** using multi-tier LLM architectures
- **Innovative Product Thinking** addressing real productivity challenges
- **ADHD-Inclusive Design** backed by cognitive science principles

Built with ❤️ for the ADHD community and productivity enthusiasts worldwide.

---

## 📞 Contact

**Gil Blinov** - [GitHub](https://github.com/BelKirill)

**Project Link**: [https://github.com/BelKirill/vikunja-mcp](https://github.com/BelKirill/vikunja-mcp)

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BelKirill](https://github.com/BelKirill)
- **Source:** [BelKirill/vikunja-mcp](https://github.com/BelKirill/vikunja-mcp)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** yes
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-belkirill-vikunja-mcp
- Seller: https://agentstack.voostack.com/s/belkirill
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.