# Vikunja MCP Server — 28 tools via DADL

The Vikunja DADL turns Vikunja's API into an MCP server that Claude, GPT or any MCP-compatible agent can consume directly. One YAML file declares all 28 tools — task, project, bucket, label, view, attachment, and more — and ToolMesh serves them at runtime. No Python boilerplate, no per-endpoint code, no separate MCP server process.

Below: the endpoint coverage matrix, a two-block ToolMesh setup, the full tool reference grouped by Vikunja feature area, required credential scopes.

**Source:** [Vikunja REST API](https://vikunja.io/docs/api/)

**Updated:** 2026-07-19

**Tags:** project-management, crud, authentication, search, user-management, auth:bearer

## Which Vikunja endpoints are covered?

**35%** (28 of ~80 endpoints).

**Focus:** projects, tasks, views, buckets, labels, comments, positions, filters, attachments

**Missing:** teams, users, shares, assignees, task relations, reactions, notifications, webhooks, subscriptions, saved filters

*Last reviewed: 2026-07-19*

## How do you configure the Vikunja DADL?

1. Log in to the Vikunja web UI
2. Open Settings → API Tokens (user menu, top right)
3. Click 'Create a token', enter a name and an optional expiry
4. Under Permissions grant at least: Projects (read & write), Tasks (read & write), Labels (read & write), Task Comments (read & write)
5. Click Create and copy the token immediately — it is shown only once (format: tk_…)

**Environment variable:** `CREDENTIAL_VIKUNJA_API_TOKEN`

[Authentication docs](https://vikunja.io/docs/api-tokens)

*Vikunja is self-hosted — replace the URL with your instance address, including the /api/v1 suffix. API tokens are shown only once at creation and their granted permissions cap what these tools can do (a read-only token returns 403 on create/update/delete).*

## How do you install the Vikunja MCP server with ToolMesh?

Add to your `backends.yaml`:

```yaml
- name: vikunja
  transport: rest
  dadl: vikunja.dadl
  url: "https://your-vikunja-instance.com/api/v1"

```

Set the credential:

```
CREDENTIAL_VIKUNJA_API_TOKEN=your-token-here
```

## What 28 tools does the Vikunja DADL expose?

- **POST** `set_task_position` — Set task position (sort order) within a project view. The position is a float64 value — use values between existing tasks to insert.
- **GET** `list_project_tasks` — List all tasks in a project view. Use view_id from list_views. Supports sorting by position, due_date, created, etc. Kanban views return buckets with nested tasks, not a flat list.
- **GET** `list_tasks` — Query tasks across ALL projects the user can access (not scoped to a single view). Supports the Vikunja filter DSL, full-text search (s) and multi-field sorting — the best endpoint for analytics/reporting (velocity, ETA, throughput): filter or sort by done_at, created, updated, due_date, percent_done. Returns a flat task array.

- **GET** `get_task` — Get a single task by its ID, including all details, assignees, labels, and relations.
- **PUT** `_create_task_raw` — Internal: raw task creation (leaves the new card at kanban position 0, i.e. the top of the board). Use the create_task composite, which appends it to the end of its bucket.
- **POST** `_update_task_raw` — Internal: raw task update (sends full object). Use the update_task composite instead.
- **POST** `move_task_to_bucket` — Move a task to a different kanban bucket. Use list_buckets to get bucket IDs. This is the only way to move tasks between kanban columns.
- **DELETE** `delete_task` — Permanently delete a task.
- **GET** `list_task_attachments` — List all attachments on a task (metadata only: attachment id, uploader, and file name/mime/size). Use download_task_attachment to fetch the bytes.
- **PUT** `upload_task_attachment` — Upload a file as an attachment to a task. ToolMesh fetches the given URL and uploads the bytes to Vikunja as the multipart form field "files". Returns the created attachment together with its stored file metadata.

- **GET** `download_task_attachment` — Download one task attachment. Returns a ToolMesh file-broker URL (file_url) to fetch the bytes, not the raw binary. For image attachments, pass preview_size to get a scaled preview instead of the original.

- **DELETE** `delete_task_attachment` — Permanently delete a task attachment.
- **GET** `list_projects` — List all projects accessible to the authenticated user. Projection now also includes parent_project_id and position (hierarchy + ordering), plus hex_color and owner (username).
- **GET** `get_project` — Get a single project by ID.
- **PUT** `create_project` — Create a new project. Only 'title' is required. Set parent_project_id to nest it under another project (hierarchy). 'identifier' (≤10 chars) is the short prefix used to build task identifiers (e.g. OPS-1); omit to auto-derive. hex_color is a 6-digit hex string without a leading '#'.

- **POST** `_update_project_raw` — Internal: raw project update (sends a full object — omitted fields are reset to zero). Use the update_project composite instead.
- **DELETE** `delete_project` — Permanently delete a project and all of its tasks, views and buckets. Irreversible. Verify the project_id with get_project first. (There is no delete for labels — those must be removed in the Vikunja UI.)

- **GET** `list_views` — List all views (list, kanban, gantt, table) for a project. Each view has its own task positions. Call this first to get view_id for list_project_tasks.
- **GET** `list_buckets` — List all kanban buckets for a project view. Returns bucket id, title, and task count. Use move_task_to_bucket to move tasks between columns.
- **PUT** `create_bucket` — Create a new kanban bucket in a project view.
- **POST** `update_bucket` — Rename a kanban bucket, set its WIP task limit, or set its position (column order — lower position is further left). title is required (Vikunja rejects an empty title); limit 0 means no limit. Sends a full bucket object, so pass the current title/limit when changing only one field (set_bucket_position does this for you). Which bucket is the DEFAULT or DONE bucket is a view property — use set_default_bucket for that, not this.

- **DELETE** `delete_bucket` — Permanently delete a kanban bucket. Its tasks are not deleted — they fall back to the view's default bucket.
- **POST** `_update_view_raw` — Internal: raw project-view update. Vikunja replaces the full view object, so omitted fields reset to zero — use the set_default_bucket composite, which reads the current view and preserves the rest.
- **GET** `list_labels` — List all labels the user has access to. Returns id, title, description, hex_color.
- **PUT** `create_label` — Create a new label. NOTE: Vikunja creates labels with PUT (not POST). 'title' is required. hex_color is a 6-digit hex string without a leading '#'. Useful for setting up reusable S/M/L estimate labels.

- **PUT** `add_label_to_task` — Add a label to a task.
- **GET** `list_task_comments` — List all comments on a task.
- **PUT** `create_task_comment` — Add a comment to a task.

## What composite workflows does the Vikunja DADL provide?

- **FN** `update_task` — Update an existing task. Only include the fields you want to change — unchanged fields are preserved (GET → merge → POST). Set project_id to MOVE the task to another project (its identifier is reassigned on move — reference by global id afterwards). To move between kanban buckets, use move_task_to_bucket instead.

- **FN** `create_task` — Create a task in a project and append it to the END of its kanban bucket (max position + step), server-side, so API-created tasks do not jump to the top of the board and disturb the priority order (board order = priority). Pass bucket_id to place it into a specific kanban bucket; omit to use the view's default bucket. Priority: 0=unset, 1=low, 2=medium, 3=high, 4=urgent, 5=critical.

- **FN** `set_default_bucket` — Set which kanban bucket is the DEFAULT (where new tasks land) and, optionally, the DONE bucket (moving a task there marks it done) for a project view. Reads the current view first and preserves its title, kind, filter and layout, so only the bucket assignments change. Get view_id from list_views (the kanban view) and bucket IDs from list_buckets.

- **FN** `set_bucket_position` — Reorder a kanban bucket (column) within its view. Pass an explicit position (float64, lower = further left), or place 'first' / 'last' to compute one from the sibling buckets (first = min/2, last = max + step). Reads the bucket first so its title and WIP limit are preserved (the raw bucket update would otherwise need them). Use this to move an Inbox column to the very left.

- **FN** `update_project` — Update an existing project. Only include the fields you want to change — unchanged fields are preserved (this composite does GET → merge → POST, because Vikunja's raw project update resets omitted fields). Set parent_project_id to re-parent (0 = top-level). To create a project use create_project.


## Which DADLs are related to Vikunja?

- [DokuWiki](https://www.dadl.ai/d/dokuwiki/) — DokuWiki JSON-RPC API — wiki pages, media files, search, ACL management, and user administration
- [Algolia HN Search](https://www.dadl.ai/d/algolia-hn-search/) — Algolia Hacker News Search API — full-text search, filtering, and retrieval for stories, comments, and users on Hacker News
- [Cloudflare](https://www.dadl.ai/d/cloudflare/) — Cloudflare API -- DNS, Pages, Workers, KV, R2, D1, Zones, SSL/TLS, Cache, Load Balancers, Firewall/WAF, Page Rules, Access (Zero Trust), and account management
- [GitLab](https://www.dadl.ai/d/gitlab/) — GitLab REST API v4 — projects, issues, merge requests, pipelines, CI/CD, and code search
- [Graylog](https://www.dadl.ai/d/graylog/) — Graylog REST API -- log search (Views/Search + legacy universal), streams, pipelines, inputs, alerts, events, dashboards, users, roles, sidecars, index management, and cluster administration. Targets Graylog 6.x.
- [Mastodon](https://www.dadl.ai/d/mastodon/) — Mastodon REST API — statuses, timelines, accounts, notifications, search, media, lists, polls, conversations, trends, filters, and instance info. Base URL must be set to the target Mastodon instance (e.g. https://mastodon.social).

---

**Canonical URL:** https://www.dadl.ai/d/vikunja/
**Raw DADL:** https://github.com/DunkelCloud/dadl-registry/blob/main/vikunja.dadl