Vikunja MCP Server
Vikunja MCP Server
A Model Context Protocol server for managing Vikunja projects and tasks.
Quick Start
Run directly with npx (no installation required):
npx vikunja-mcp --token YOUR_VIKUNJA_TOKENWith custom Vikunja URL:
npx vikunja-mcp --url https://your-vikunja.com/api/v1 --token YOUR_TOKENOr using environment variables:
export VIKUNJA_TOKEN=your_token
export VIKUNJA_URL=https://your-vikunja.com/api/v1
npx vikunja-mcpRelated MCP server: vikunja-mcp
Features
Full CRUD operations for projects
Full CRUD operations for tasks
Task comments management
Task relations (subtasks, blocking, etc.)
Task attachments listing
Task assignees management
Task labels management
Project hierarchy (epics) management
Available Tools
Projects
Tool | Description |
| List all projects the user has access to |
| Get a specific project by ID |
| Create a new project |
| Update an existing project |
| Delete a project by ID |
| List child projects under a project |
| Move project to different parent/position |
Tasks
Tool | Description |
| List all tasks across all projects |
| List all tasks for a specific project |
| Get a specific task by ID |
| Create a new task in a project |
| Update an existing task |
| Delete a task by ID |
Task State & Movement
Tool | Description |
| Mark a task as done |
| Reopen a completed task |
| Move task to different project/position |
Assignees
Tool | Description |
| Add a user as assignee to a task |
| Remove assignee from a task |
| List all assignees for a task |
Labels
Tool | Description |
| Add a label to a task |
| Remove a label from a task |
| List all labels on a task |
| List all available labels (globally) |
Comments
Tool | Description |
| List all comments for a task |
| Add a comment to a task |
| Update a comment |
| Delete a comment |
Relations
Tool | Description |
| Create a relation between two tasks |
| Delete a relation between tasks |
| List all relations for a task |
Subtasks
Tool | Description |
| Create a subtask linked to parent task |
| List all subtasks for a task |
Attachments
Tool | Description |
| List all attachments for a task |
| Delete an attachment from a task |
See below for complete parameter documentation for all tools.
Tool Reference
Parameter Types
string: Text value
number: Numeric value (integer)
boolean: true/false value
required: This parameter must be provided
optional: This parameter can be omitted
Note: All ID parameters (e.g.,
projectId,taskId) accept both number and string values. The MCP server usesz.coerce.number()to automatically convert string IDs (like "123") to numbers. This means you can pass either123or"123"for any ID parameter. See Using String IDs for examples.
Projects
list_projects
List all projects the user has access to.
Parameters: None required
Optional:
page(number): Page number for paginationper_page(number): Number of items per page (default: 25)
get_project
Get a specific project by ID.
Parameters:
projectId(number, required): The project ID
create_project
Create a new project.
Parameters:
title(string, required): The project title
Optional:
description(string): Project descriptionhex_color(string): Hex color code (e.g., "#FF5733")identifier(string): Unique identifier for the projectparent_project_id(number): ID of parent project (for epics/hierarchy)is_archived(boolean): Whether the project is archived
update_project
Update an existing project.
Parameters:
projectId(number, required): The project ID
Optional:
title(string): New titledescription(string): New descriptionhex_color(string): New hex color codeidentifier(string): New identifierparent_project_id(number): New parent project IDis_archived(boolean): Archive status
delete_project
Delete a project by ID.
Parameters:
projectId(number, required): The project ID
list_project_children
List child projects under a project.
Parameters:
projectId(number, required): The parent project ID
move_project
Move project to different parent or position.
Parameters:
projectId(number, required): The project ID
Optional:
parent_project_id(number): New parent project ID (null to remove from parent)position(number): New position in the parent project
Tasks
list_tasks
List all tasks across all projects.
Parameters: None required
Optional:
page(number): Page number for paginationper_page(number): Number of items per pagestatus(string): Filter by status (open, done, done_lte, done_gte)priority(number): Filter by prioritydue_date(string): Filter by due datelabel(string): Filter by label
list_project_tasks
List all tasks for a specific project.
Parameters:
projectId(number, required): The project ID
Optional:
page(number): Page number for paginationper_page(number): Number of items per page
get_task
Get a specific task by ID.
Parameters:
taskId(number, required): The task ID
create_task
Create a new task in a project.
Parameters:
projectId(number, required): The project ID
Required:
task(object): The task objecttitle(string, required): The task title
Optional:
task(object): The task objectdescription(string): Task descriptiondone(boolean): Whether task is completeddue_date(string): Due date (ISO 8601 format)start_date(string): Start dateend_date(string): End datehex_color(string): Task colorpriority(number): Priority (1-5, where 5 is highest)percent_done(number): Progress (0-100)repeat_after(number): Repeat after X minutesrepeat_mode(number): Repeat mode (0=relative, 1=absolute)
update_task
Update an existing task.
Parameters:
taskId(number, required): The task IDtaskUpdates(object, required): The task fields to update
Optional:
taskUpdates(object):title(string): New titledescription(string): New descriptiondone(boolean): Completion statusdue_date(string): New due datestart_date(string): New start dateend_date(string): New end datehex_color(string): New colorpriority(number): New prioritypercent_done(number): Progress (0-100)repeat_after(number): New repeat intervalrepeat_mode(number): Repeat mode (0=relative, 1=absolute)
delete_task
Delete a task by ID.
Parameters:
taskId(number, required): The task ID
Task State & Movement
complete_task
Mark a task as done.
Parameters:
taskId(number, required): The task ID
reopen_task
Reopen a completed task.
Parameters:
taskId(number, required): The task ID
move_task
Move task to different project or position.
Parameters:
taskId(number, required): The task IDproject_id(number, required): Target project ID
Optional:
position(number): New position
Assignees
add_task_assignee
Add a user as assignee to a task.
Parameters:
taskId(number, required): The task IDuserId(number, required): The user ID to add
remove_task_assignee
Remove assignee from a task.
Parameters:
taskId(number, required): The task IDuserId(number, required): The user ID to remove
list_task_assignees
List all assignees for a task.
Parameters:
taskId(number, required): The task ID
Labels
add_task_label
Add a label to a task.
Parameters:
taskId(number, required): The task IDlabel_id(number, required): The label ID to add
remove_task_label
Remove a label from a task.
Parameters:
taskId(number, required): The task IDlabel_id(number, required): The label ID to remove
list_task_labels
List all labels on a task.
Parameters:
taskId(number, required): The task ID
list_labels
List all available labels (globally).
Parameters: None required
Optional:
project_id(number): Filter by project IDpage(number): Page numberper_page(number): Items per page
Comments
list_comments
List all comments for a task.
Parameters:
taskId(number, required): The task ID
Optional:
page(number): Page numberper_page(number): Items per page
create_comment
Add a comment to a task.
Parameters:
taskId(number, required): The task IDcomment(string, required): The comment text
update_comment
Update a comment.
Parameters:
taskId(number, required): The task IDcommentId(number, required): The comment IDcomment(string, required): New comment text
delete_comment
Delete a comment.
Parameters:
taskId(number, required): The task IDcommentId(number, required): The comment ID to delete
Relations
create_relation
Create a relation between two tasks.
Parameters:
taskId(number, required): The source task IDotherTaskId(number, required): The related task IDrelationKind(string, required): Relation type (unknown, subtask, parenttask, related, duplicateof, duplicates, blocking, blocked, precedes, follows, copiedfrom, copiedto)
delete_relation
Delete a relation between tasks.
Parameters:
taskId(number, required): The source task IDotherTaskId(number, required): The related task IDrelationKind(string, required): Relation type (unknown, subtask, parenttask, related, duplicateof, duplicates, blocking, blocked, precedes, follows, copiedfrom, copiedto)
list_task_relations
List all relations for a task.
Parameters:
taskId(number, required): The task ID
Subtasks
create_subtask
Create a subtask linked to parent task.
Parameters:
projectId(number, required): The project IDparent_task_id(number, required): The parent task IDtask(object, required): The subtask object
Required:
task(object):title(string, required): The subtask title
Optional:
task(object):description(string): Subtask descriptiondone(boolean): Whether subtask is completeddue_date(string): Due datestart_date(string): Start dateend_date(string): End datehex_color(string): Subtask colorpriority(number): Prioritypercent_done(number): Progress (0-100)repeat_after(number): Repeat after X minutesrepeat_mode(number): Repeat mode (0=relative, 1=absolute)
list_subtasks
List all subtasks for a task.
Parameters:
taskId(number, required): The parent task ID
Attachments
list_task_attachments
List all attachments for a task.
Parameters:
taskId(number, required): The task ID
Optional:
page(number): Page numberper_page(number): Items per page
delete_task_attachment
Delete an attachment from a task.
Parameters:
taskId(number, required): The task IDattachmentId(number, required): The attachment ID
Examples
Listing Projects and Tasks
list my vikunja projectsReturns all projects you have access to.
list_project_tasks projectId: 1Returns all tasks in project ID 1.
list_tasks per_page: 50Lists up to 50 tasks across all projects.
Creating Projects and Tasks
create_project title: "My Project" description: "A new project" hex_color: "#FF5733"Creates a new project with a title, description, and color.
create_task projectId: 1 title: "Buy groceries" priority: 3 due_date: "2024-12-25"Creates a task in project ID 1 with priority and due date.
Managing Task State
complete_task taskId: 5Marks task 5 as done.
reopen_task taskId: 5Reopens task 5.
Working with Assignees
add_task_assignee taskId: 3 userId: 7Adds user 7 as assignee to task 3.
list_task_assignees taskId: 3Lists all assignees for task 3.
Comments
create_comment taskId: 3 comment: "This should be done by Friday"Adds a comment to task 3.
Relations
create_relation taskId: 1 otherTaskId: 2 relationKind: "blocking"Creates a "blocks" relation from task 1 to task 2 (task 1 blocks task 2).
Using String IDs
All ID parameters accept strings, so these are equivalent:
get_project projectId: 1
get_project projectId: "1"This is useful when working with data from external sources:
list_project_tasks projectId: "123"Installation
Prerequisites
Node.js 18+
npm or bun
A Vikunja instance (self-hosted or cloud)
Vikunja API token
Getting a Vikunja API Token
Log into your Vikunja instance
Go to Settings → API Tokens
Create a new token
Build from Source
git clone https://github.com/Wosh-i/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run buildOpenCode Configuration
Option 1: Using npx (Recommended)
The easiest way to configure Vikunja MCP is using npx. Add this to your OpenCode config (~/.config/opencode/opencode.jsonc):
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vikunja": {
"type": "local",
"command": ["npx", "-y", "vikunja-mcp"],
"environment": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_TOKEN": "your-api-token-here",
},
},
},
}Using npx with -y skips the confirmation prompt and automatically downloads the package.
Option 2: Build from Source
If you prefer to run locally without npx, build from source:
git clone https://github.com/Wosh-i/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run buildThen configure OpenCode:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vikunja": {
"type": "local",
"command": ["node", "/path/to/vikunja-mcp/dist/index.js"],
"environment": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_TOKEN": "your-api-token-here",
},
},
},
}Configuration Options
Option | Required | Default | Description |
| No | Your Vikunja API base URL | |
| Yes | - | Your Vikunja API token |
Environment Variables
You can also set environment variables globally in your shell:
export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"Then the OpenCode config can be simpler:
{
"$schema": "https://opencode.ai/config.json",
"mcp": {
"vikunja": {
"type": "local",
"command": ["node", "/path/to/vikunja-mcp/dist/index.js"],
},
},
}Claude Code Desktop App Configuration
Option 1: Using npx (Recommended)
The easiest way to configure Vikunja MCP is using npx. Add this to your Claude Code desktop config file:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"vikunja": {
"command": "npx",
"args": ["-y", "vikunja-mcp"],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_TOKEN": "your-api-token-here",
},
},
},
}Using npx with -y skips the confirmation prompt and automatically downloads the package.
Option 2: Build from Source
If you prefer to run locally without npx, build from source:
git clone https://github.com/Wosh-i/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run buildThen configure Claude Code:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
{
"mcpServers": {
"vikunja": {
"command": "node",
"args": ["/path/to/vikunja-mcp/dist/index.js"],
"env": {
"VIKUNJA_URL": "https://your-vikunja-instance.com/api/v1",
"VIKUNJA_TOKEN": "your-api-token-here",
},
},
},
}Configuration Options
Option | Required | Default | Description |
| No | Your Vikunja API base URL | |
| Yes | - | Your Vikunja API token |
Environment Variables
You can also set environment variables globally in your shell:
export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"Then the Claude Code config can be simpler:
{
"mcpServers": {
"vikunja": {
"command": "node",
"args": ["/path/to/vikunja-mcp/dist/index.js"],
},
},
}Claude Code TUI Configuration
The Claude Code TUI (terminal user interface) uses the claude mcp add command to configure MCP servers.
Option 1: Using npx (Recommended)
The easiest way to configure Vikunja MCP is using npx:
claude mcp add --transport stdio --env VIKUNJA_URL=https://your-vikunja-instance.com/api/v1 --env VIKUNJA_TOKEN=your-api-token-here vikunja -- npx -y vikunja-mcpOption 2: Build from Source
If you prefer to run locally without npx, build from source:
git clone https://github.com/Wosh-i/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run buildThen configure Claude Code:
claude mcp add --transport stdio --env VIKUNJA_URL=https://your-vikunja-instance.com/api/v1 --env VIKUNJA_TOKEN=your-api-token-here vikunja -- /path/to/vikunja-mcp/dist/index.jsConfiguration Scopes
Claude Code TUI supports different scopes for MCP server configuration:
Scope | Config Location | Description |
|
| Available to you across all projects |
|
| Available only in the current project |
|
| Shared with team members (checked into source control) |
# Add with user scope (available across all projects)
claude mcp add --transport stdio --scope user --env VIKUNJA_TOKEN=... vikunja -- npx -y vikunja-mcp
# Add with project scope (shared with team via .mcp.json)
claude mcp add --transport stdio --scope project --env VIKUNJA_TOKEN=... vikunja -- npx -y vikunja-mcpManaging MCP Servers
# List all configured servers
claude mcp list
# Get details for a specific server
claude mcp get vikunja
# Remove a server
claude mcp remove vikunja
# Within Claude Code, check server status
/mcpConfiguration Options
Option | Required | Default | Description |
| No | Your Vikunja API base URL | |
| Yes | - | Your Vikunja API token |
Environment Variables
You can also set environment variables globally in your shell:
export VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
export VIKUNJA_TOKEN="your-api-token-here"Then the configuration is simpler:
claude mcp add --transport stdio vikunja -- npx -y vikunja-mcpUsage
CLI Options
Option | Alias | Description |
|
| Your Vikunja API token |
|
| Your Vikunja API base URL |
|
| Show help |
Using with OpenCode
After configuration, you can use Vikunja tools in OpenCode:
list my vikunja projectscreate a project called "My Tasks" with color #FF5733add a task titled "Buy groceries" to project "My Tasks" with priority 3show me all tasks in the Inbox projectDevelopment
# Install dependencies
npm install
# Build
npm run build
# Run in development mode
npm run dev
# Run tests (when available)
npm testLicense
MIT License - see LICENSE file for details.
Contributing
Contributions welcome! Please open an issue or pull request.
Available Tools
33 toolsadd_task_assigneeC
Add a user as assignee to a task
Inputs: taskId (required), user_id (required).
add_task_labelC
Add a label to a task
Inputs: taskId (required), label_id (required).
complete_taskC
Mark a task as done
Inputs: taskId (required).
create_projectC
Create a new project
Inputs: title (required), description, hex_color, identifier, +2 more.
create_relationC
Create a relation between two tasks
Inputs: taskId (required), otherTaskId (required), relationKind (required).
create_subtaskC
Create a subtask under a parent task
Inputs: projectId (required), task (required), parent_task_id (required).
create_taskC
Create a new task in a project
Inputs: projectId (required), task (required).
delete_commentC
Delete a comment from a task
Inputs: taskId (required), commentId (required).
delete_projectC
Delete a project by ID
Inputs: projectId (required).
delete_relationC
Delete a relation between two tasks
Inputs: taskId (required), otherTaskId (required), relationKind (required).
delete_taskC
Delete a task by ID
Inputs: taskId (required).
delete_task_attachmentC
Delete an attachment from a task
Inputs: taskId (required), attachmentId (required).
get_projectC
Get a specific project by ID
Inputs: projectId (required).
get_taskC
Get a specific task by ID
Inputs: taskId (required), expand.
list_attachmentsC
List all attachments for a specific task
Inputs: taskId (required), page, per_page.
list_commentsC
List all comments for a specific task
Inputs: taskId (required), commentId (required), comment (required).
list_labelsC
List all available labels
Inputs: project_id.
list_project_childrenC
List all child projects of a project
Inputs: projectId (required).
list_projectsC
List all projects the user has access to
Inputs: page, per_page.
list_project_tasksC
List all tasks for a specific project
Inputs: projectId (required), page, per_page.
list_subtasksB
List all subtasks for a task
Inputs: taskId (required).
list_task_assigneesC
List all assignees for a task
Inputs: taskId (required).
list_task_labelsC
List all labels for a task
Inputs: taskId (required).
list_task_relationsC
List all relations for a task
Inputs: taskId (required).
list_tasksB
List all tasks across all projects
Inputs: page, per_page, search, sort_by, +3 more.
move_projectC
Move a project to a different parent or position
Inputs: projectId (required), parent_project_id, position.
move_taskC
Move a task to a different project or position
Inputs: taskId (required), project_id (required), position.
move_task_to_bucketC
Move a task to a different kanban bucket
Inputs: taskId (required), projectId (required), viewId (required), bucketId (required), +1 more.
remove_task_assigneeC
Remove a user from task assignees
Inputs: taskId (required), userId (required).
remove_task_labelC
Remove a label from a task
Inputs: taskId (required), labelId (required).
reopen_taskC
Reopen a completed task
Inputs: taskId (required).
update_projectC
Update an existing project
Inputs: projectId (required), title, description, hex_color, +4 more.
update_taskC
Update an existing task
Inputs: taskId (required), taskUpdates (required).
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 33 tools
Every tool has a clearly distinct purpose with no ambiguity. Tools are precisely scoped to specific actions on specific resources (e.g., add_task_assignee vs. remove_task_assignee, create_task vs. update_task vs. delete_task). The descriptions reinforce this clarity, making misselection unlikely.
Tool names follow a highly consistent verb_noun pattern throughout (e.g., create_project, list_tasks, update_task). All names use snake_case uniformly, and verbs are predictable (create, get, list, update, delete, add, remove, move, complete, reopen). This consistency enhances readability and predictability.
With 33 tools, the count feels heavy for a task management server, bordering on excessive. While the tools cover many operations, a more streamlined set might improve usability. This is borderline, as it could overwhelm agents but is not extreme.
The tool surface is complete for the Vikunja task management domain. It covers full CRUD/lifecycle operations for projects, tasks, comments, attachments, labels, assignees, and relations, with no obvious gaps. Agents can perform all expected workflows without dead ends.
Maintenance
Related MCP Connectors
Create and manage MeisterTask projects, tasks, and notes from your AI assistant.
Manage tasks, Focus Zone, notes, projects, and task history from compatible AI assistants.
Manage Redbooth tasks, task lists, comments, tags and files from Claude and other AI assistants.
Manage Superlist tasks and lists in plain language from any MCP-compatible AI agent.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceConnects Claude to self-hosted Vikunja instances for conversational task and project management. Supports CRUD operations on projects and tasks, plus labels, comments, weekly reviews, calendar feeds, and task relations.-
- AlicenseCqualityCmaintenanceEnables AI assistants to interact with Vikunja task management via ergonomic and raw REST tools for projects, tasks, labels, and comments.1006 npmMIT
- AlicenseCqualityFmaintenanceEnables AI assistants to interact with Vikunja task management instances, providing full task, project, label, team, user, and webhook management operations through subcommand-based tools.16260 npm113MIT
- AlicenseNot gradedqualityDmaintenanceEnables to interact with Vikunja task management through its REST API, supporting projects, tasks, comments, labels, assignees, and relations with field preservation.ISC