Vikunja MCP Server

by democratize-technology

88 stars

780 downloads

Not rated

GitHub

About

Model Context Protocol server for Vikunja task management. Enables AI assistants to interact with Vikunja instances via MCP.

Details

Author: democratize-technology
GitHub stars: 88
Downloads: 780
Categories: Other, Productivity, Project Management

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 Server

Command (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

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

JSON

{
    "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"
                }
            }
        }
    }
}

From the repository

Install via npx -y @democratize-technology/vikunja-mcp or build locally, then configure environment variables VIKUNJA_URL and VIKUNJA_API_TOKEN (or JWT token) in your MCP client. Use subcommand tools like vikunja_tasks.create and vikunja_auth.connect after authentication.

`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"
        }
    }
}

Vikunja MCP Server

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 maintainability

Zod-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 reliability

Production-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 patterns

Zero 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

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Jump to

Setting up with Highlight

From the repository

vikunja_auth

vikunja_tasks

vikunja_projects

vikunja_labels

vikunja_teams

vikunja_filters

vikunja_templates

vikunja_webhooks

vikunja_batch_import

Claude Desktop / Cursor

McpServers

Vikunja MCP Server

Features

🚀 Major Architectural Improvements (v0.2.0)

Storage Architecture Refactoring (90% Code Reduction)

Zod-Based Filter System (850+ Lines Removed)

Production-Ready Retry System (580+ Lines Replaced)

Zero Breaking Changes

Requirements

Installation

Option 1: Install from NPM (Recommended)

Option 2: Local Development

Configuration

Logging Configuration

Install

More like this

Sequential Thinking

Time

Filesystem

EverArt

Google Drive

GitLab

`vikunja_auth`

`vikunja_tasks`

`vikunja_projects`

`vikunja_labels`

`vikunja_teams`

`vikunja_filters`

`vikunja_templates`

`vikunja_webhooks`

`vikunja_batch_import`