┌────────────────────────────────────────────────────────────┐
│ │
│ ██╗ ██╗██╗██╗ ██╗██╗ ██╗███╗ ██╗ ██╗ █████╗ │
│ ██║ ██║██║██║ ██╔╝██║ ██║████╗ ██║ ██║██╔══██╗ │
│ ██║ ██║██║█████╔╝ ██║ ██║██╔██╗ ██║ ██║███████║ │
│ ╚██╗ ██╔╝██║██╔═██╗ ██║ ██║██║╚██╗██║██ ██║██╔══██║ │
│ ╚████╔╝ ██║██║ ██╗╚██████╔╝██║ ╚████║╚█████╔╝██║ ██║ │
│ ╚═══╝ ╚═╝╚═╝ ╚═╝ ╚═════╝ ╚═╝ ╚═══╝ ╚════╝ ╚═╝ ╚═╝ │
│ ███╗ ███╗ ██████╗██████╗ │
│ ████╗ ████║██╔════╝██╔══██╗ │
│ ██╔████╔██║██║ ██████╔╝ │
│ ██║╚██╔╝██║██║ ██╔═══╝ │
│ ██║ ╚═╝ ██║╚██████╗██║ │
│ ╚═╝ ╚═╝ ╚═════╝╚═╝ │
│ │
│ > MCP server for Vikunja task management │
│ > Connect your AI assistant to your tasks │
│ │
└────────────────────────────────────────────────────────────┘
Connect your AI assistant to Vikunja, the open-source task manager. This MCP server lets you manage projects, tasks, kanban boards, and more—just by asking. Works with Claude Desktop, OpenCode, Cursor, and other MCP clients.
WHY VIKUNJA-MCP?
────────────────────────────────────────────────────────────
[+] Self-hosted friendly Your data stays on your server
[+] Full coverage 32 tools across all Vikunja APIs
[+] Reliable Retry logic with exponential backoff
[+] Production ready 86 tests, 90%+ code coverage
[+] Zero config Works out of the box with npx
────────────────────────────────────────────────────────────
# Install
$ npm install -g @0xk3vin/vikunja-mcp
# Set environment variables
$ export VIKUNJA_URL="https://your-vikunja-instance.com"
$ export VIKUNJA_API_TOKEN="your_api_token"Add to your config file:
- macOS:
~/Library/Application Support/Claude/claude_desktop_config.json - Windows:
%APPDATA%/Claude/claude_desktop_config.json
{
"mcpServers": {
"vikunja": {
"command": "npx",
"args": ["-y", "@0xk3vin/vikunja-mcp"],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com",
"VIKUNJA_API_TOKEN": "your_api_token"
}
}
}
}┌─────────────────────────────────────────────────────────┐
│ │
│ [■] PROJECTS Create, update, delete, archive │
│ [■] TASKS Full CRUD + filtering & sorting │
│ [■] KANBAN Buckets, move tasks, WIP limits │
│ [■] LABELS Create, attach, remove from tasks │
│ [■] COMMENTS Add and list task comments │
│ [■] ASSIGNEES Manage who's working on what │
│ [■] RELATIONS Subtasks, blocking, dependencies │
│ [■] VIEWS List, kanban, table, gantt │
│ [■] TEAMS List teams and members │
│ [■] USERS Search by name, username, email │
│ [■] NOTIFICATIONS List user notifications │
│ │
└─────────────────────────────────────────────────────────┘
Copy .env.example to .env and configure:
VIKUNJA_URL=https://your-vikunja-instance.com
VIKUNJA_API_TOKEN=your_api_tokenGetting an API token:
- Log into your Vikunja instance
- Go to Settings → API Tokens
- Create a new token and copy it
$ git clone https://github.com/0xK3vin/vikunja-mcp.git
$ cd vikunja-mcp
$ npm install
$ npm run build
$ npm test| Command | Description |
|---|---|
npm start |
Run the server |
npm test |
Run tests |
npm run build |
Build TypeScript |
npm run lint |
Lint code |
npm run inspect |
Debug with MCP Inspector |
Full API reference: docs/API.md
Contributions welcome! See CONTRIBUTING.md for guidelines.
MIT - see LICENSE
╔════════════════════════════════════════════════════════════╗
║ Made by 0xK3vin ║
║ github.com/0xK3vin/vikunja-mcp ║
╚════════════════════════════════════════════════════════════╝