Altiplano
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| VIKUNJA_URL | No | The URL of the Vikunja API. Must end in /api/v1 or /api/v2 (e.g., https://todo.example.com/api/v2). | |
| ALTIPLANO_CONFIG | No | Path to a file containing KEY=VALUE pairs (defaulting to ~/.config/altiplano/env) with VIKUNJA_URL and VIKUNJA_API_TOKEN. Use absolute paths; ~ is not expanded in custom paths. | |
| VIKUNJA_API_TOKEN | No | The Vikunja API token with scopes covering the tools you intend to call. |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Altiplano exposes a Vikunja instance as MCP tools.
Before writing anything:
Ids are volatile. Resolve a project, label, kanban view, column, or user by name with the matching list or search tool, then carry the id through the session. Never guess an id, and re-resolve one remembered from an earlier session.
search_tasks()finds a task when its project is unknown.list_tasks()needs one.delete_task(),delete_label(), anddelete_comment()cannot be undone through this API. Confirm the target withget_task()first.move_task_to_bucket()writes state: the done column marks a task done, and moving it out reopens it. To close a task, callupdate_task()withdone: true.create_task()takes nodoneparameter. Recording finished work means acreate_task()call followed by anupdate_task()call.filterandsort_bytake Vikunja's server-side syntax, for exampledone = false && priority >= 4.
Fetch the altiplano_guide prompt for the rest: cross-tool sequencing, batching,
kanban behaviour, relations, the differences between the v1 and v2 APIs, and what
breaks when deploying altiplano-http as a shared service for several clients.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| search_usersA | Search users by name or username. Use this to find a user_id for assignees. |
| list_assigneesC | List the users assigned to a task. |
| add_assigneeC | Assign a user to a task. |
| remove_assigneeB | Unassign a user from a task. |
| list_commentsA | List comments on a task. |
| add_commentC | Add a comment to a task. |
| update_commentA | Replace the text of an existing comment. Get |
| delete_commentB | Delete a comment from a task. Get |
| list_kanban_viewsA | List a project's kanban views, with the bucket ids that give them meaning. Most projects have one. Pass an
|
| list_bucketsA | List the columns of a project's kanban view, in board order. The columns alone, with no tasks in them.
|
| create_bucketA | Add a column to a project's kanban view. It goes on the right-hand end.
|
| update_bucketA | Rename a column, or change how many tasks it accepts.
Neither API version has a partial update for a bucket. This reads the column and
writes it back whole, and a body with only a title resets Position is preserved. To move a column, use the Vikunja web interface: this API exposes no ordering call. |
| delete_bucketA | Delete a column from a project's kanban view. Vikunja moves the tasks it held to the default bucket, leaving them intact. A view keeps at least one column, and the last one cannot be removed. |
| list_boardA | The whole board: a kanban view's columns with the tasks sitting in each.
|
| list_task_placementsC | Where one task sits: the column holding it, one entry per kanban view. A task holds a position in every kanban view of its project. A project with two boards puts the task in two columns. Usually there is one. The |
| move_task_to_bucketA | Move a task into a kanban bucket. Re-sending the same bucket does nothing. This changes more than the column, and
Only meaningful when the view's The project is read from the task. That costs a request and removes an argument that could contradict the task it was given. |
| list_labelsA | List all labels. |
| create_labelA | Create a label, which
|
| update_labelB | Update a label. Only the fields you pass change. Every task with the label sees the change.
v1 has no partial update, and neither does a description change on v2. Both read the label and write it back with your changes merged in, at the cost of one extra request. Everything else on v2 is a single PATCH. |
| delete_labelA | Delete a label everywhere. It comes off every task that has it.
|
| add_labelB | Attach a label to a task. |
| remove_labelB | Remove a label from a task. |
| list_projectsA | List all projects (boards). Vikunja leaves archived projects out of this endpoint. |
| create_projectA | Create a project. Pass |
| update_projectA | Update a project. Only the fields you pass change.
v1 has no partial update, and neither does a description change on v2. Both read the project and write it back with your changes merged in, at the cost of one extra request. Everything else on v2 is a single PATCH. |
| delete_projectA | Delete a project, everything in it, and every project under it. This cascades. Deleting a parent takes its sub-projects, every task in all of them, and each task's comments, labels, and assignees. Checked against Vikunja 2.5.0 with a parent, one sub-project, and a task: all three ids read 404 afterwards. Vikunja soft-deletes and documents a 30 day retention window, while exposing no
endpoint to list or restore anything deleted. Through this API the call is
permanent. Confirm the id with To put a project out of the way and keep it, call |
| add_relationA | Relate one task to another. Defaults to a plain, symmetric Kinds: subtask, parenttask, related, duplicateof, duplicates, blocking, blocked, precedes, follows, copiedfrom, copiedto.
|
| remove_relationA | Remove a relation between two tasks. The kind has to match the one the relation was created with; see
|
| list_tasksA | List tasks in a project.
|
| search_tasksA | Search tasks across every project you can see.
|
| get_taskB | Get a single task with full detail. On v2 the description is Markdown. |
| create_taskA | Create a task in a project.
|
| bulk_create_tasksA | Create several tasks in one project, in one request. Needs the v2 API. Vikunja creates the batch atomically: if one entry is invalid then none are
created, and the error names the entry that failed. The tasks also keep the
order they were given. A loop of Each entry is an object taking the same fields as Returns a summary per created task, in creation order. Call |
| update_taskA | Update a task. Only the fields you pass change. Use v1 has no partial update. There, this reads the task and writes it back with your changes merged in, at the cost of one extra request. v2 is a single PATCH unless a description is involved.
Two wrinkles in what comes back. On v2 a partial update returns the description
as the stored HTML. v2 does not convert on a PATCH. Call |
| move_taskA | Move a task to another project. Needs write access to the target. Vikunja has no endpoint for this. A task's Labels, assignees, comments, relations, and dates all come along. The
project-local |
| duplicate_taskA | Copy a task, with its labels, assignees, attachments, and reminders. The copy lands in the same project as the original and links back to it with a
Returns the copy, with the |
| bulk_update_tasksA | Set Only the fields you pass are written, on either API version. This endpoint takes the field names separately from the values. That makes it a genuine partial update on v1 too, where updating a single task is a replace. You need write access to every project involved. If it is missing on even one, the whole request is refused and nothing changes. Up to Vikunja 2.7.0 the same endpoint also cleared every assignee and reminder
and unset the favourite flag on each task it touched. The server's release is
read once from |
| set_remindersA | Replace a task's reminders with the given ISO 8601 datetimes. Empty list clears them. Nothing else about the task changes. On v1 that costs an extra request: its update endpoint is a replace, and the task has to be read and written back whole. On v2 it is a single partial update. |
| delete_taskA | Delete a task. There is no way to undo this through the API. Vikunja soft-deletes, and documents deleted tasks as retained for 30 days before permanent removal, while exposing no endpoint to list or restore them. The row outlives the task and stays unreachable from here. Treat this as irreversible and confirm the id first. Deleting a task also takes its comments, labels, and assignees with it. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| altiplano_guide | How to drive Altiplano's tools: resolving ids, sequencing calls across tools, the calls that cannot be undone, the v1 and v2 differences, and what breaks when deploying `altiplano-http` as a shared service. Load this before making changes through the tools. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 39 tools
The tool set is largely clean: labels (create/add/remove/update/delete), comments, assignees, relations, and tasks each have clearly distinct actions, and near-neighbors are explicitly disambiguated in prose (list_board vs list_buckets vs list_kanban_views vs list_task_placements; list_tasks vs search_tasks; move_task vs move_task_to_bucket). The remaining risk is the cluster of read tools around kanban views/buckets/board, where an agent must read the descriptions carefully to pick correctly, and set_reminders vs update_task on reminders overlaps conceptually.
Every tool follows a predictable verb_noun or verb_noun_phrase schema (list_*, get_*, create_*, update_*, delete_*, add_*, remove_*, move_*, search_*, bulk_*, set_*, duplicate_*). Qualifiers are used consistently (add_* = attach to a task, remove_* = detach, bulk_* = batch variants of create/update). No camelCase or style mixing.
39 tools is well past the comfortable 3-15 band and beyond the 25+ 'heavy' threshold, so the surface is large. In fairness the domain is genuinely broad (projects, tasks, labels, comments, assignees, buckets, kanban views, relations, reminders, users, bulk operations) and each tool maps to a real distinct operation rather than filler. Still, it leans heavy and could be trimmed (e.g. list_board/list_buckets/list_kanban_views/list_task_placements consolidation, bulk_create/bulk_update fold-in).
Coverage is strong: full CRUD for projects, tasks, labels, comments, buckets, relations, assignees, plus bulk create/update, cross-project search, duplication, move, and reminders. The notable gaps are attachments (duplicate_task mentions copying attachments, yet no attachment list/upload/delete tool exists) and single-resource reads for projects/buckets (only list endpoints), which agents can mostly work around.