How do I use Vikunja MCP Server?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@Vikunja MCP Server create a task called 'Review Q3 report' in the Marketing project" That's it! The server will respond to your query, and you can continue using it as needed. Here is a step-by-step guide with screenshots.

Vikunja MCP Server

A Model Context Protocol server for managing Vikunja projects and tasks.

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_projects`	List all projects the user has access to
`get_project`	Get a specific project by ID
`create_project`	Create a new project
`update_project`	Update an existing project
`delete_project`	Delete a project by ID
`list_project_children`	List child projects under a project
`move_project`	Move project to different parent/position

Tasks

Tool	Description
`list_tasks`	List all tasks across all projects
`list_project_tasks`	List all tasks for a specific project
`get_task`	Get a specific task by ID
`create_task`	Create a new task in a project
`update_task`	Update an existing task
`delete_task`	Delete a task by ID

Task State & Movement

Tool	Description
`complete_task`	Mark a task as done
`reopen_task`	Reopen a completed task
`move_task`	Move task to different project/position

Assignees

Tool	Description
`add_task_assignee`	Add a user as assignee to a task
`remove_task_assignee`	Remove assignee from a task
`list_task_assignees`	List all assignees for a task

Labels

Tool	Description
`add_task_label`	Add a label to a task
`remove_task_label`	Remove a label from a task
`list_task_labels`	List all labels on a task
`list_labels`	List all available labels (globally)

Comments

Tool	Description
`list_comments`	List all comments for a task
`create_comment`	Add a comment to a task
`update_comment`	Update a comment
`delete_comment`	Delete a comment

Relations

Tool	Description
`create_relation`	Create a relation between two tasks
`delete_relation`	Delete a relation between tasks
`list_task_relations`	List all relations for a task

Subtasks

Tool	Description
`create_subtask`	Create a subtask linked to parent task
`list_subtasks`	List all subtasks for a task

Attachments

Tool	Description
`list_task_attachments`	List all attachments for a task
`delete_task_attachment`	Delete an attachment from a task

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/YOUR_USERNAME/vikunja-mcp.git
cd vikunja-mcp
npm install
npm run build

OpenCode Configuration

Add the following to your OpenCode config (~/.config/opencode/opencode.jsonc):

{
  "$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
`VIKUNJA_URL`	No	https://try.vikunja.io/api/v1	Your Vikunja API base URL
`VIKUNJA_TOKEN`	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"],
    },
  },
}

Usage

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.

This server cannot be installed

-

security - not tested

A

license - permissive license

-

quality - not tested

How are these scores calculated?

Resources

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Vikunja MCP Server

Vikunja MCP Server

Features

Available Tools

Projects

Tasks

Task State & Movement

Assignees

Labels

Comments

Relations

Subtasks

Attachments

Installation

Prerequisites

Getting a Vikunja API Token

Build from Source

OpenCode Configuration

Configuration Options

Environment Variables

Usage

Development

License

Contributing

Resources

Looking for Admin?

Latest Blog Posts

MCP directory API