vikunja-mcp

@AnthonyUtt

About vikunja-mcp

Basic MCP server for interacting with Vikunja to-do app

Config

Add this server to your MCP-compatible client using the configuration below.

{
  "mcpServers": {
    "vikunja": {
      "command": "npx",
      "args": [
        "-y",
        "vikunja-mcp"
      ],
      "env": {
        "VIKUNJA_API_BASE": "https://app.vikunja.cloud",
        "VIKUNJA_API_TOKEN": ""
      }
    }
  }
}

Tools

List all projects

Get a specific project by ID

Create a new project

Update an existing project

Delete a project by ID

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 by ID

Delete a specific task by ID. This action cannot be undone, so use with caution.

Create a relation between two tasks

Delete a relation between two tasks

Get the comments for a specific task

Create a comment for a specific task

Update a comment for a specific task

Delete a comment for a specific task

List all attachments for a specific task

Attach a file to a task

Get a specific attachment for a task

Delete a specific attachment for a task

Overview

What is vikunja-mcp?

vikunja-mcp is a basic Model Context Protocol server for Vikunja, a task management platform. It enables AI assistants like Claude to interact with Vikunja to manage projects and tasks.

How to use vikunja-mcp?

Install it via npx or build locally, then configure your MCP client with the vikunja-mcp command and environment variables VIKUNJA_API_BASE and VIKUNJA_API_TOKEN. For example, add a "vikunja" entry under mcpServers in your Claude configuration.

Key features of vikunja-mcp

List all projects
Get a project by its ID
List all tasks across projects
List tasks within a specific project
Add a task with title, description, and done fields
Update and delete existing tasks

Use cases of vikunja-mcp

List all projects and their details
View tasks in a specific project
Add new tasks to a project
Update or delete tasks via conversation

FAQ from vikunja-mcp

What dependencies or runtime are required?

Node.js and either npx (for quick start) or a local clone with pnpm installed for building.

How does authentication work?

You provide a Vikunja API token via the VIKUNJA_API_TOKEN environment variable. The token must have appropriate permissions for the operations you intend to use.

What transport does the server use?

It runs as a subprocess via stdio – the command and arguments are specified in the client’s MCP server configuration.

What are the limits of the "add task" operation?

Only the title, description, and done fields are supported when adding a task.

Where are my data stored?

All data resides in your Vikunja instance, which is accessed via the VIKUNJA_API_BASE URL you configure. The server does not store anything locally.

Frequently asked questions

What dependencies or runtime are required?

Node.js and either `npx` (for quick start) or a local clone with `pnpm` installed for building.

How does authentication work?

You provide a Vikunja API token via the `VIKUNJA_API_TOKEN` environment variable. The token must have appropriate permissions for the operations you intend to use.

What transport does the server use?

It runs as a subprocess via `stdio` – the command and arguments are specified in the client’s MCP server configuration.

What are the limits of the "add task" operation?

Only the `title`, `description`, and `done` fields are supported when adding a task.

Where are my data stored?

All data resides in your Vikunja instance, which is accessed via the `VIKUNJA_API_BASE` URL you configure. The server does not store anything locally.