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_TOKEN

With custom Vikunja URL:

npx vikunja-mcp --url https://your-vikunja.com/api/v1 --token YOUR_TOKEN

Or using environment variables:

export VIKUNJA_TOKEN=your_token
export VIKUNJA_URL=https://your-vikunja.com/api/v1
npx 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

Tasks

Task State & Movement

Assignees

Labels

Comments

Relations

Subtasks

Attachments

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 uses z.coerce.number() to automatically convert string IDs (like "123") to numbers. This means you can pass either 123 or "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 pagination

  • per_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 description

  • hex_color (string): Hex color code (e.g., "#FF5733")

  • identifier (string): Unique identifier for the project

  • parent_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 title

  • description (string): New description

  • hex_color (string): New hex color code

  • identifier (string): New identifier

  • parent_project_id (number): New parent project ID

  • is_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 pagination

  • per_page (number): Number of items per page

  • status (string): Filter by status (open, done, done_lte, done_gte)

  • priority (number): Filter by priority

  • due_date (string): Filter by due date

  • label (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 pagination

  • per_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 object

    • title (string, required): The task title

• Optional:

  • task (object): The task object

    • description (string): Task description

    • done (boolean): Whether task is completed

    • due_date (string): Due date (ISO 8601 format)

    • start_date (string): Start date

    • end_date (string): End date

    • hex_color (string): Task color

    • priority (number): Priority (1-5, where 5 is highest)

    • percent_done (number): Progress (0-100)

    • repeat_after (number): Repeat after X minutes

    • repeat_mode (number): Repeat mode (0=relative, 1=absolute)

update_task

Update an existing task.

• Parameters:

  • taskId (number, required): The task ID

  • taskUpdates (object, required): The task fields to update

• Optional:

  • taskUpdates (object):

    • title (string): New title

    • description (string): New description

    • done (boolean): Completion status

    • due_date (string): New due date

    • start_date (string): New start date

    • end_date (string): New end date

    • hex_color (string): New color

    • priority (number): New priority

    • percent_done (number): Progress (0-100)

    • repeat_after (number): New repeat interval

    • repeat_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 ID

  • project_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 ID

  • userId (number, required): The user ID to add

remove_task_assignee

Remove assignee from a task.

• Parameters:

  • taskId (number, required): The task ID

  • userId (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 ID

  • label_id (number, required): The label ID to add

remove_task_label

Remove a label from a task.

• Parameters:

  • taskId (number, required): The task ID

  • label_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 ID

  • page (number): Page number

  • per_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 number

  • per_page (number): Items per page

create_comment

Add a comment to a task.

• Parameters:

  • taskId (number, required): The task ID

  • comment (string, required): The comment text

update_comment

Update a comment.

• Parameters:

  • taskId (number, required): The task ID

  • commentId (number, required): The comment ID

  • comment (string, required): New comment text

delete_comment

Delete a comment.

• Parameters:

  • taskId (number, required): The task ID

  • commentId (number, required): The comment ID to delete

Relations

create_relation

Create a relation between two tasks.

• Parameters:

  • taskId (number, required): The source task ID

  • otherTaskId (number, required): The related task ID

  • relationKind (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 ID

  • otherTaskId (number, required): The related task ID

  • relationKind (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 ID

  • parent_task_id (number, required): The parent task ID

  • task (object, required): The subtask object

• Required:

  • task (object):

    • title (string, required): The subtask title

• Optional:

  • task (object):

    • description (string): Subtask description

    • done (boolean): Whether subtask is completed

    • due_date (string): Due date

    • start_date (string): Start date

    • end_date (string): End date

    • hex_color (string): Subtask color

    • priority (number): Priority

    • percent_done (number): Progress (0-100)

    • repeat_after (number): Repeat after X minutes

    • repeat_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 number

  • per_page (number): Items per page

delete_task_attachment

Delete an attachment from a task.

• Parameters:

  • taskId (number, required): The task ID

  • attachmentId (number, required): The attachment ID

Examples

Listing Projects and Tasks

list my vikunja projects

Returns all projects you have access to.

list_project_tasks projectId: 1

Returns all tasks in project ID 1.

list_tasks per_page: 50

Lists 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: 5

Marks task 5 as done.

reopen_task taskId: 5

Reopens task 5.

Working with Assignees

add_task_assignee taskId: 3 userId: 7

Adds user 7 as assignee to task 3.

list_task_assignees taskId: 3

Lists 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

1. Log into your Vikunja instance

2. Go to Settings → API Tokens

3. Create a new token

Build from Source

git clone https://github.com/Wosh-i/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run build

OpenCode 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 build

Then 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

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 build

Then 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

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-mcp

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 build

Then 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.js

Configuration Scopes

Claude Code TUI supports different scopes for MCP server configuration:

# 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-mcp

Managing 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
/mcp

Configuration Options

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-mcp

Usage

CLI Options

Using with OpenCode

After configuration, you can use Vikunja tools in OpenCode:

list my vikunja projects

create a project called "My Tasks" with color #FF5733

add a task titled "Buy groceries" to project "My Tasks" with priority 3

show me all tasks in the Inbox project

Development

# Install dependencies
npm install

# Build
npm run build

# Run in development mode
npm run dev

# Run tests (when available)
npm test

License

MIT License - see LICENSE file for details.

Contributing

Contributions welcome! Please open an issue or pull request.