Vikunja MCP Server
About
Model Context Protocol server for Vikunja task management. Enables AI assistants to interact with Vikunja instances via MCP.
Explore
- Subcommand-based tools for intuitive AI interactions
- Session-based authentication with automatic token management
- Full task management operations implemented
- Complete project management with CRUD operations
- Label management for organizing tasks
- Team operations for collaboration (get/update/members limited by API)
- User management with settings and search
- Webhook management for project automation
- Batch import tasks from CSV or JSON files
- Input validation for dates, IDs, and hex colors
- Efficient diff-based updates for assignees
- TypeScript with strict mode for type safety
- Comprehensive error handling with typed errors and centralized utilities
- Production-ready retry logic with opossum circuit breaker for resilience
- Enhanced security with Zod-based input validation and DoS protection
- Rate limiting protection against DoS attacks with configurable limits
- Memory protection with pagination limits and usage monitoring
- Simplified architecture with 90% code reduction for maintainability
Setting up with Highlight
This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:
- Download and install Highlight from highlightai.com/download
- Navigate to the plugins tab and select "Add Custom Plugin"
-
Configure the plugin with the settings below
Plugin Name
Vikunja MCP ServerCommand (node, npx, python, etc.)Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
- Enable "Start Automatically" if you want the plugin to start when Highlight launches
From the repository
- Node.js 20+ (LTS versions only)
- Vikunja instance with API access
- API token (starting with tk_) or JWT token for authentication
The easiest way to use vikunja-mcp is through npx in your Claude Desktop or other MCP-compatible client configuration:
{
"vikunja": {
"command": "npx",
"args": ["-y", "@democratize-technology/vikunja-mcp"],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_API_TOKEN": "your-api-token"
}
}
}
The server includes a structured logging system. Configure it via environment variables:
The Vikunja MCP server supports two authentication methods, each with different capabilities:
API tokens are the standard authentication method for Vikunja:
- How to obtain: Go to Vikunja Settings → API Tokens → Create new token
- Token format: Starts with tk_ (e.g., tk_abc123def456)
- Capabilities: Full access to tasks, projects, labels, teams, and webhooks
- Limitations: Cannot access user-specific endpoints (user profile, settings, export)
- Best for: Automation, CI/CD, and general task management
JWT (JSON Web Token) authentication provides full access to all Vikunja endpoints:
- How to obtain: Extract from your browser session (see instructions below)
- Token format: Long string starting with eyJ (standard JWT format)
- Capabilities: Full access to all endpoints including user management and export
- Limitations: Tokens expire (typically after 24 hours)
- Best for: User management, data export, and operations requiring user context
// Connect with JWT token - automatically detected!
vikunja_auth.connect({
apiUrl: "https://your-vikunja-instance.com/api/v1",
apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
})
Important Notes:
- JWT tokens expire; you'll need to extract a new one when it expires
- Token type is automatically detected based on format (no flag needed)
- Some tools (users, export) are only available with JWT authentication
// Connect with API token (automatically detected)
vikunja_auth.connect({
apiUrl: "https://your-vikunja-instance.com/api/v1",
apiToken: "tk_your-api-token"
})
// Connect with JWT token (automatically detected, enables additional tools: users, export)
vikunja_auth.connect({
apiUrl: "https://your-vikunja-instance.com/api/v1",
apiToken: "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
})
// Check authentication status
vikunja_auth.status()
// Disconnect and clean up resources
vikunja_auth.disconnect()
```
vikunja_auth
vikunja_tasks
vikunja_projects
vikunja_labels
vikunja_teams
vikunja_filters
vikunja_templates
vikunja_webhooks
vikunja_batch_import
Claude Desktop / Cursor
Paste into your MCP client config file to install this server.
{
"mcpServers": {
"vikunja mcp server": {
"vikunja": {
"command": "npx",
"args": [
"-y",
"@democratize-technology/vikunja-mcp"
],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_API_TOKEN": "your-api-token"
}
}
}
}
}McpServers
{
"vikunja": {
"command": "npx",
"args": [
"-y",
"@democratize-technology/vikunja-mcp"
],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_API_TOKEN": "your-api-token"
}
}
}A Model Context Protocol (MCP) server that enables AI assistants to interact with Vikunja task management instances.
Features
- Subcommand-based tools for intuitive AI interactions
- Session-based authentication with automatic token management
- Full task management operations implemented
- Complete project management with CRUD operations
- Label management for organizing tasks
- Team operations for collaboration (get/update/members limited by API)
- User management with settings and search
- Webhook management for project automation
- Batch import tasks from CSV or JSON files
- Input validation for dates, IDs, and hex colors
- Efficient diff-based updates for assignees
- TypeScript with strict mode for type safety
- Comprehensive error handling with typed errors and centralized utilities
- Production-ready retry logic with opossum circuit breaker for resilience
- Enhanced security with Zod-based input validation and DoS protection
- Rate limiting protection against DoS attacks with configurable limits
- Memory protection with pagination limits and usage monitoring
- Simplified architecture with 90% code reduction for maintainability
🚀 Major Architectural Improvements (v0.2.0)
This release represents a massive architectural simplification that eliminates technical debt while enhancing security and reliability:
Storage Architecture Refactoring (90% Code Reduction)
- Before: 33 files, 9,803 lines of over-engineered storage system - After: 4 files, essential functionality only - Eliminated: Complex orchestrators, health monitors, statistics tracking, migration systems - Result: Same external API with dramatically improved maintainabilityZod-Based Filter System (850+ Lines Removed)
- Before: Custom tokenizer, parser, and validator with security vulnerabilities - After: Secure Zod schema validation with production-ready parsing - Enhanced: DoS protection, input sanitization, and comprehensive error handling - Result: Faster parsing, better security, and enterprise-grade reliabilityProduction-Ready Retry System (580+ Lines Replaced)
- Before: Custom retry logic with maintenance overhead - After: Battle-tested opossum circuit breaker library - Features: Circuit breaker state sharing, automatic recovery, comprehensive monitoring - Result: Production resilience with battle-tested patternsZero Breaking Changes
All improvements maintain 100% backward compatibility with existing implementations while providing enhanced reliability and security.Requirements
- Node.js 20+ (LTS versions only)
- Vikunja instance with API access
- API token (starting with tk_) or JWT token for authentication
Installation
Option 1: Install from NPM (Recommended)
The easiest way to use vikunja-mcp is through npx in your Claude Desktop or other MCP-compatible client configuration:
{
"vikunja": {
"command": "npx",
"args": ["-y", "@democratize-technology/vikunja-mcp"],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_API_TOKEN": "your-api-token"
}
}
}
Option 2: Local Development
For development or customization:
git clone https://github.com/democratize-technology/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run build
Then configure your MCP client:
{
"vikunja": {
"command": "node",
"args": ["/path/to/vikunja-mcp/dist/index.js"],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_API_TOKEN": "your-api-token"
}
}
}
Configuration
Logging Configuration
The server includes a structured logging system. Configure it via environment variables:
```bash
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
