Altiplano
Altiplano is an MCP server for Vikunja that lets you manage projects, tasks, kanban boards, labels, comments, assignees, and task relations.
Projects: list, create, update, delete projects and sub-projects; archive/unarchive projects.
Tasks: list, search, get, create, update, move, duplicate, and delete tasks; bulk create/update tasks; set reminders; manage dates, priority, progress, favorites, and repeats.
Kanban: list kanban views, buckets, and full boards; create, update, and delete buckets; find task placements and move tasks between buckets.
Labels: list, create, update, and delete labels; attach/remove labels on tasks.
Comments: list, add, update, and delete task comments.
Assignees: search users; list, add, and remove task assignees.
Relations: add and remove task relations such as subtask, blocking, related, duplicate, and copied links.

Altiplano
A small, dependable MCP server for Vikunja. Named after the Andean altiplano, the high plateau that is the Vicuña's native habitat.
Altiplano runs locally through uvx, or as a stand-alone HTTP service that several people share on one endpoint, each acting as their own Vikunja user. Both modes expose the same tools and the same guidance.
Choose how to use Altiplano
Local, through | Shared, over HTTP | |
Where Altiplano runs | On your computer, launched by your MCP client. | On a host running Altiplano as a stand-alone service. |
How your MCP client connects | Runs | Connects to the service URL with a valid bearer token. |
Requirements on your computer |
| An MCP client supporting Streamable HTTP and a configured |
Where the Vikunja credentials live | On each computer running Altiplano. | On the service host, one token per client. |
Setup |
Connecting to an existing HTTP service needs its URL and an Altiplano client token. You do not need to install Altiplano,
uv, or Python on the client.
The configuration examples below use an mcpServers block. Adapt the surrounding structure to your MCP client's configuration format.
Related MCP server: ticktick-mcp
Use locally with uvx
Your MCP client launches Altiplano as a local subprocess and communicates with it over stdio. Each client manages its own Altiplano process.
1. Install uv
uv provides the uvx command, which runs Altiplano from PyPI without a repository checkout.
2. Configure Vikunja credentials
Create an API token in Vikunja under Settings → API Tokens, reachable from the menu under your username. Give it the scopes covering the tools you intend to call. See Vikunja's API documentation.
mkdir -p ~/.config/altiplanoCreate ~/.config/altiplano/env containing:
VIKUNJA_URL=https://altiplano.example.com/api/v2
VIKUNJA_API_TOKEN=tk_replace_meRestrict the file's permissions:
chmod 600 ~/.config/altiplano/envAltiplano checks these sources in order:
The
VIKUNJA_URLandVIKUNJA_API_TOKENenvironment variables.A file containing
KEY=VALUEpairs, defaulting to~/.config/altiplano/env.
Set ALTIPLANO_CONFIG before starting Altiplano to read a different file. Use absolute paths; ~ is not expanded in custom paths.
VIKUNJA_URLmust end in/api/v1or/api/v2. That suffix selects the version, for examplehttps://altiplano.example.com/api/v2.
Vikunja 2.4.0 introduced
/api/v2. Altiplano strips trailing slashes and enables v2 only for a URL ending in/api/v2. Every other URL keeps its configured path and uses v1 request verbs. Use/api/v2when the server supports it.
Permissions broader than
600produce a warning on POSIX systems and startup continues. An unreadable file is ignored after a warning.
3. Configure your MCP client
Add a local server entry:
{
"mcpServers": {
"altiplano": {
"command": "uvx",
"args": ["--refresh-package", "altiplano", "altiplano@latest"]
}
}
}
--refresh-package altiplanochecks PyPI for a current release. If an older version still starts, close the client and runuv cache clean altiplano.
4. Verify with one call
Restart or reconnect your MCP client, then call list_projects(). Any list, an empty one included, confirms that Altiplano reaches Vikunja with the configured credentials.
Altiplano speaks MCP over stdio. Running
uvx altiplanoin a terminal prints nothing and waits for a client on stdin and stdout.
Use over HTTP
altiplano-http serves the same tools over Streamable HTTP from one always-on host. Each client presents its own bearer token, which Altiplano mints, stores as a SHA-256 hash, and revokes one at a time.
The service must already be running and reachable from the computer running your MCP client. Adding its URL to your client configuration connects to the service. It does not start it. DEPLOYMENT.md covers standing one up, and Docker is the shortest path there.
One endpoint serves several people, each as their own Vikunja user. There is no shared Vikunja API token: the host holds one per registered client, and a request is made with the token belonging to the client that sent it. Two people on one service reach their own projects and their own tasks, with Vikunja applying its own permissions to each.
Registering a client is a manual step for whoever operates the host. An unrecognised client token is refused with
401. A registered client whose record holds no Vikunja token is refused with403.
Connect to an existing service
Obtain the MCP endpoint URL and a client token from whoever operates the host server. If that is you, Register clients has the steps.
Use one client token per client. Sharing one works, at two costs: the clients all act as the same Vikunja user, and revoking it cuts off every one of them.
claude mcp add --transport http altiplano \
https://altiplano.example.com/mcp \
--header "Authorization: Bearer altp_replace_me"The equivalent in a client's own configuration:
{
"mcpServers": {
"altiplano": {
"type": "http",
"url": "https://altiplano.example.com/mcp",
"headers": {
"Authorization": "Bearer altp_replace_me"
}
}
}
}type: Not part of the MCP protocol, which covers the wire format and leaves the configuration shape to each client. They disagree: some require
type, some spell the valuestreamable-httpand othershttp, some call the keytransport, and some infer the transport fromurlalone. Use the form your client documents.url: Replace it with the real endpoint, including its port and path where required. The example assumes HTTPS is configured for the service.
headers: The bearer token here is an Altiplano client token, issued by
altiplano-clientkey, and it says which client is calling. Your Vikunja API token is a separate thing: it stays on the service host, registered against your client, and it is the identity your requests act as. Give the operator a token from your own Vikunja account.
A client that only launches subprocesses cannot reach an HTTP URL at all. Keep the stdio entry on those machines.
Restart or reconnect your MCP client, then call list_projects(). A successful response confirms the connection, the client token, and access to Vikunja.
Keep the client token private. It grants access to the service and every tool it exposes. Ask the operator to revoke and replace a lost or exposed token. A revocation applies to the next request.
The supported path is a client that sends the header you configure. Altiplano answers an unauthenticated request with a bare
WWW-Authenticate: Bearerchallenge and publishes no OAuth metadata. A client may still probe the well-known metadata URLs on its own initiative and will get a404. A client that can only obtain credentials through an OAuth flow is not supported here.
Tools
list_projects(include_archived=False): includesparent_project_idfor sub-projects andis_archived. Vikunja omits archived projects from this endpoint;include_archived=Trueadds them back alongside the active ones.create_project(title, parent_project_id?, description?): passparent_project_idto create a sub-project.update_project(project_id, title?, description?, parent_project_id?, is_archived?, hex_color?): changes only the supplied fields and requires at least one.is_archivedarchives and unarchives, and Vikunja has no separate archive endpoint.hex_coloris six hexadecimal digits without#.delete_project(project_id): deletes the project, its sub-projects, and every task in all of them, along with each task's comments, labels, and assignees. Vikunja retains them for 30 days and provides no restore endpoint. Treat deletion as irreversible, and preferupdate_project(project_id, is_archived=True)to set a project aside.
Archiving hides a project from
list_projectsunlessinclude_archived=True. Vikunja also refuses every other edit to an archived project, and to the tasks in it, with a412. Unarchive it first.
list_tasks(project_id, filter?, sort_by?, page=1, per_page=50): Vikunja appliesfilterandsort_bybefore pagination.search_tasks(query?, filter?, sort_by?, page=1, per_page=50): searches all visible projects and includesproject_idin each result. Vikunja does not combine text search withfilter.get_task(task_id): returns full task detail. On v2, the description is Markdown.create_task(project_id, title, description?, priority?, due_date?, start_date?, end_date?, percent_done?, is_favorite?, repeat_after?, repeat_mode?)update_task(task_id, title?, description?, done?, priority?, due_date?, start_date?, end_date?, percent_done?, is_favorite?, repeat_after?, repeat_mode?): changes only the supplied fields and requires at least one. Pass an empty string fordue_date,start_date, orend_dateto clear it.move_task(task_id, project_id): moves labels, assignees, comments, relations, and dates with the task. The destination project assigns a new localidentifier.duplicate_task(task_id): copies the task, labels, assignees, attachments, and reminders into the same project. The copy receives acopiedfromrelation to the original.bulk_create_tasks(project_id, tasks): creates a batch of tasks in one request, atomically and in the given order. Requires/api/v2. Each entry takes the same fields ascreate_task,titleincluded, anything else is refused. Vikunja caps a batch at 100 and names the entry that fails. Returns one summary per created task.bulk_update_tasks(task_ids, done?, priority?): requires at least one field and Vikunja 2.7.1 or later. The request fails as a unit if the token lacks write access to any affected project. Up to Vikunja 2.7.0 the bulk endpoint also cleared assignees, reminders, and the favourite flag on each task, and the tool refuses there.set_reminders(task_id, reminders): replaces all reminders with the supplied ISO 8601 datetimes. Pass an empty list to clear them.delete_task(task_id): soft-deletes the task and removes its comments, labels, and assignees. Vikunja retains the task for 30 days and provides no restore endpoint. Treat deletion as irreversible.
list_kanban_views(project_id): includes the default and done bucket IDs.list_buckets(project_id, view_id?): returns columns in board order and marks the default and done columns.create_bucket(project_id, title, view_id?, limit?): adds a column at the right. Omitlimit, or pass0, for no limit.update_bucket(project_id, bucket_id, title?, limit?, view_id?): renames a column or changes its limit, and requires at least one field. Neither API version offers a partial update here. The call reads the column and writes it back whole. Column order is not writable.delete_bucket(project_id, bucket_id, view_id?): moves the column's tasks to the default column. Vikunja will not remove the last column.list_board(project_id, view_id?, filter?): returns columns and their tasks.task_countremains the full count when Vikunja caps the returned task list. Takes the same arguments aslist_bucketsand adds the tasks and their counts.list_task_placements(task_id): returns the column holding the task, one entry for each kanban view.move_task_to_bucket(task_id, bucket_id, view_id?): reads the project ID from the task.
Bucket behaviour:
Bucket operations require a view with
view_kind="kanban". Withoutview_id, Altiplano uses the first kanban view in the project's view order.bucket_configuration_mode="manual"accepts explicit moves. Infiltermode, filters determine the column.A move into a full bucket fails.
Moving a task into the done column closes it; moving it out reopens it.
A repeating task moved into the done column reopens in the default column.
Setting
doneto true throughupdate_taskmoves the task into the done column.
add_relation(task_id, other_task_id, relation_kind="related")remove_relation(task_id, other_task_id, relation_kind="related"): use the same kind that created the relation.
get_taskreturnsrelated_tasks, grouped by kind. Supported kinds aresubtask,parenttask,related,duplicateof,duplicates,blocking,blocked,precedes,follows,copiedfrom, andcopiedto.
add_relation(task_id, other_task_id, "subtask")makesother_task_ida child oftask_id.
list_labels(), create_label(title, hex_color?, description?), update_label(label_id, title?, hex_color?, description?), delete_label(label_id), add_label(task_id, label_id), remove_label(task_id, label_id).
hex_coloris six hexadecimal digits without#.update_labelchanges only the supplied fields and requires at least one; every task with the label shows the change. Deleting a label removes it from every task.
list_comments(task_id), add_comment(task_id, comment), update_comment(task_id, comment_id, comment), delete_comment(task_id, comment_id).
update_commentreplaces the complete text. Getcomment_idfromlist_comments.
search_users(query), list_assignees(task_id), add_assignee(task_id, user_id), remove_assignee(task_id, user_id).
Use
search_usersto find theuser_idrequired by the assignment tools.
Guidance
Altiplano documents its own use in four places.
The handshake sends usage rules: resolve ids by name, which calls cannot be undone, how to close a task. Clients apply them on connect.
The
altiplano_guideprompt holds the full version, with cross-tool sequencing and the v1 and v2 differences. Clients list it asUsing Altiplano.AGENTS.mdcovers working on this repository, and installing Altiplano for someone else.CLAUDE.mdimports it, for Claude Code.DEPLOYMENT.mdcovers running the HTTP transport as a service on a host: Docker with aDockerfileand a compose file, a two-commanduvpath with no clone, every environment variable the transport reads, minting client tokens, encrypting the connection, four checks that say whether it works, and an FAQ of the ways it fails.
Task behaviour
Task updates
Both API versions preserve fields omitted from an update.
On v1, POST /tasks/{id} replaces the complete task. Altiplano reads the current task, merges the changes, and writes it back for update_task, set_reminders, and move_task. Each call costs one extra request.
On v2, those calls use PATCH. A description change uses a read and full replacement because PATCH does not apply Markdown conversion.
When a v2 read includes an ETag, Altiplano sends it in If-Match during the replacement. Vikunja returns HTTP 412 if the task changed between the read and write. Read the task again before retrying. V1 and v2 responses without an ETag have no concurrency guard.
Dates, priority, and progress
Priorities use Vikunja's scale:
0Unset,1Low,2Medium,3High,4Urgent, and5DO NOW.Dates are ISO 8601 datetimes.
start_dateandend_datedefine the work window;due_dateis the deadline.An empty string clears a date by writing Vikunja's zero time,
0001-01-01T00:00:00Z.percent_doneis a fraction. A quarter complete is0.25. Vikunja does not clamp the value, and50remains50.
Repeating tasks
repeat_after is measured in seconds. Completing a repeating task reopens it and advances its due date and reminders.
repeat_mode values:
0: advance the existing dates byrepeat_after.1: repeat monthly and ignorerepeat_after.2: calculate the next occurrence from the completion date.
Vikunja's v1 specification lists 3 in the repeat_mode description; its generated enum defines the final mode as 2.
A repeating task with no dates reopens immediately and cannot remain closed. Set a due_date when enabling repetition.
Identifiers and errors
The Vikunja UI displays a project-local identifier, such as #50. API calls use the global numeric id.
Failed requests include Vikunja's detail, message, or title field when present. Altiplano also includes a non-zero numeric error code when Vikunja provides one. Redirects are errors and include the destination.
Requests time out after 30 seconds and are not retried.
Markdown
Vikunja stores task descriptions and comments as HTML. Altiplano requests Markdown conversion for full task reads, task creates, project creates, comment reads and writes, and full task replacements.
The v1 API has no Markdown conversion. Markdown sent through v1 is stored literally.
V2 partial updates through update_task, move_task, and set_reminders return the stored HTML description. Call get_task to retrieve Markdown. An update_task call that changes description uses a full replacement.
Vikunja resolves @mentions during Markdown conversion and notifies the named user.
Compatibility
Tested with Vikunja 2.5.0 against /api/v1 and /api/v2, and with 2.8.0 against /api/v2.
Identified issues:
Up to Vikunja 2.7.0,
/tasks/bulkcleared every assignee and reminder and unset the favourite flag on each task it touched, on top of the fields it was asked to write. Vikunja 2.7.1 fixed it.bulk_update_tasksreads the server's release once from/infoand refuses below 2.7.1.On Vikunja 2.5.0, the v2 grouped-bucket route used by
list_boardmay return HTTP 401 when the token works elsewhere. Try a new full-permission token or/api/v1. The same diagnosis is returned for every v2 HTTP 401 from that route. Verify the token itself too.list_bucketsreads a different route and is unaffected.On Vikunja 2.3.0,
list_assigneesreturns HTTP 500. The endpoint worked on 2.5.0.
Contributing
Pull requests are always welcome. CONTRIBUTING.md covers the development setup, the commands, the pre-commit hook, the source layout, and what a pull request needs. Taking part means agreeing to the code of conduct.
Licence
MIT.
Support
RTFM, then RTFS. If you are still stuck, or just need an additional feature, file an issue.
Available Tools
39 toolsadd_assigneeC
Assign a user to a task.
Inputs: task_id (required), user_id (required).
add_commentC
Add a comment to a task.
Inputs: comment (required), task_id (required).
add_labelB
Attach a label to a task.
Inputs: task_id (required), label_id (required).
add_relationA
Relate one task to another. Defaults to a plain, symmetric related link.
Kinds: subtask, parenttask, related, duplicateof, duplicates, blocking, blocked, precedes, follows, copiedfrom, copiedto.
task_id is the base task and other_task_id is the one being related to it.
That direction decides the asymmetric kinds: subtask makes the other task a
child of this one. Needs write access to the base task and read access to the
other; they do not have to be in the same project.
Inputs: task_id (required), other_task_id (required), relation_kind.
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 create_task calls races: a numbered plan can
come back shuffled, and a failure halfway through leaves the rest uncreated.
Each entry is an object taking the same fields as create_task. title is
required; description, priority, due_date, start_date, end_date,
percent_done, is_favorite, repeat_after, and repeat_mode are optional
and mean what they do there, including an empty string to clear a date.
Anything else is refused. A dropped key would read as a task created with a
date or a priority it never got. Vikunja caps a batch at 100.
Returns a summary per created task, in creation order. Call get_task for the
full detail of one.
Inputs: tasks (required), project_id (required). Returns: result
bulk_update_tasksA
Set done or priority on many tasks in one request. Needs Vikunja 2.7.1 or later.
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 /info, and below 2.7.1 this tool refuses and writes nothing.
update_task per task is the safe path there.
Inputs: task_ids (required), done, priority.
create_bucketA
Add a column to a project's kanban view. It goes on the right-hand end.
limit caps how many tasks the column accepts, and moves into a full one are
refused; leave it out, or pass 0, for no limit.
Inputs: title (required), project_id (required), limit, view_id.
create_labelA
Create a label, which add_label can then attach to tasks.
hex_color is six hex digits with no leading #, as list_labels reports them.
description is rich text, written as Markdown. Vikunja stores it as HTML and
v2 converts on the way in.
Inputs: title (required), hex_color, description.
create_projectA
Create a project. Pass parent_project_id to create it as a sub-project.
Inputs: title (required), description, parent_project_id.
create_taskA
Create a task in a project.
start_date and end_date are ISO 8601 datetimes marking the window you
plan to work on the task (start work / finish work), distinct from
due_date (the deadline).
percent_done is a fraction despite the name. A quarter done is 0.25. Vikunja
does not validate it, and 50 is stored as 50.
repeat_after is a number of seconds, and repeating happens when the task is
marked done: it reopens itself and moves its due date and reminders forward.
repeat_mode is 0 to advance by repeat_after, 1 to repeat monthly and ignore
repeat_after, or 2 to count from the day it was completed. Give a repeating
task a due_date. It reopens whether or not there is a date to advance, and one
with no dates can never be closed.
Inputs: title (required), project_id (required), due_date, end_date, +7 more.
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.
Inputs: bucket_id (required), project_id (required), view_id.
delete_commentB
Delete a comment from a task. Get comment_id from list_comments.
Inputs: task_id (required), comment_id (required).
delete_labelA
Delete a label everywhere. It comes off every task that has it.
remove_label takes a label off one task and leaves the label itself alone.
Inputs: label_id (required).
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 list_projects first, and look there for a
parent_project_id matching this one: any project that names it goes too.
To put a project out of the way and keep it, call update_project with
is_archived: true.
Inputs: project_id (required).
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.
Inputs: task_id (required).
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
copiedfrom relation. Vikunja offers no way to duplicate straight into another
project; call move_task on the copy for that.
Returns the copy, with the id a caller needs to act on it. Vikunja wraps
this one response in a duplicated_task envelope on both API versions, and that
wrapper is removed here. A body without the key is passed through whole.
Inputs: task_id (required).
get_taskB
Get a single task with full detail. On v2 the description is Markdown.
Inputs: task_id (required).
list_assigneesC
List the users assigned to a task.
Inputs: task_id (required). Returns: result
list_boardA
The whole board: a kanban view's columns with the tasks sitting in each.
list_buckets answers the thinner question, the columns alone, and takes the same
arguments. Reach for that one when the tasks are of no interest, and for this one
when they are.
task_count is the column's true size, which can exceed the tasks returned:
Vikunja caps how many it sends per column. To reach the rest, narrow with
filter, the same server-side syntax list_tasks takes.
Inputs: project_id (required), filter, view_id. Returns: result
list_bucketsA
List the columns of a project's kanban view, in board order.
The columns alone, with no tasks in them. list_board takes the same arguments and
returns each column with its tasks.
limit is the most tasks the bucket accepts, where 0 means no limit; a move into
a full bucket is refused. Vikunja does not populate task counts on this endpoint,
and list_board reports them.
Inputs: project_id (required), view_id. Returns: result
list_commentsA
List comments on a task.
Inputs: task_id (required). Returns: result
list_kanban_viewsA
List a project's kanban views, with the bucket ids that give them meaning.
Most projects have one. Pass an id from here as view_id to the bucket tools
to target a specific one.
bucket_configuration_mode is manual when you arrange tasks yourself, or
filter when Vikunja builds a bucket per filter. In filter mode, moving a
task between buckets is unavailable.
Inputs: project_id (required). Returns: result
list_labelsA
List all labels.
Inputs: no named parameters. Returns: result
list_projectsA
List all projects (boards). parent_project_id shows sub-project nesting.
Vikunja leaves archived projects out of this endpoint. include_archived adds
them back alongside the active ones, and is_archived on each result says which
is which. An archived project is otherwise unreachable through this tool, and its
id is what update_project needs to bring it back.
Inputs: include_archived. Returns: result
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 bucket_id on a task read any other way is 0. That field only means
something inside a view.
Inputs: task_id (required). Returns: result
list_tasksA
List tasks in a project.
filter and sort_by are passed to Vikunja and applied server-side, e.g.
filter="done = false && priority >= 4", sort_by="priority". Vikunja filters
then paginates. Results are complete at any page size.
Inputs: project_id (required), page, filter, sort_by, +1 more. Returns: result
move_taskA
Move a task to another project. Needs write access to the target.
Vikunja has no endpoint for this. A task's project_id is writable and setting
it is the move. This costs what an update costs: two requests on v1, one on v2.
Labels, assignees, comments, relations, and dates all come along. The
project-local identifier derives from the project the task is in, and is
reassigned on arrival.
Inputs: task_id (required), project_id (required).
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 list_kanban_views tells you which
bucket is which:
Moving into the done bucket marks the task done, and moving it out un-marks it.
A repeating task moved into the done bucket is reopened and sent to the default bucket.
A bucket at its task limit refuses the move.
Only meaningful when the view's bucket_configuration_mode is manual. In
filter mode the filters decide which bucket a task sits in.
The project is read from the task. That costs a request and removes an argument that could contradict the task it was given.
Inputs: task_id (required), bucket_id (required), view_id.
remove_assigneeB
Unassign a user from a task.
Inputs: task_id (required), user_id (required).
remove_labelB
Remove a label from a task.
Inputs: task_id (required), label_id (required).
remove_relationA
Remove a relation between two tasks.
The kind has to match the one the relation was created with; see
add_relation for the list. get_task reports what a task currently has.
Inputs: task_id (required), other_task_id (required), relation_kind.
search_tasksA
Search tasks across every project you can see.
list_tasks needs to be told a project. This is the tool for "find this task,
I do not remember where it lives", and every result reports its project_id.
query is a text search over titles and descriptions. filter and sort_by are
the same server-side syntax list_tasks takes. Vikunja documents the text search
as incompatible with a filter. Use one or the other.
Inputs: page, query, filter, sort_by, +1 more. Returns: result
search_usersA
Search users by name or username. Use this to find a user_id for assignees.
Inputs: query (required). Returns: result
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.
Inputs: task_id (required), reminders (required).
update_bucketA
Rename a column, or change how many tasks it accepts.
limit is the most tasks the column takes, and 0 means no limit. Lowering it
below the number already there is allowed: Vikunja keeps them and refuses the
next move in.
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 limit to 0 on both
versions. There is also no endpoint for reading one bucket. The read comes from the
view's bucket list, and a bucket_id absent from that view is refused before
anything is written.
Position is preserved. To move a column, use the Vikunja web interface: this API exposes no ordering call.
Inputs: bucket_id (required), project_id (required), limit, title, +1 more.
update_commentA
Replace the text of an existing comment. Get comment_id from list_comments.
Inputs: comment (required), task_id (required), comment_id (required).
update_labelB
Update a label. Only the fields you pass change. Every task with the label sees the change.
hex_color is six hex digits with no leading #, and an empty string clears it.
description is Markdown.
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.
Inputs: label_id (required), title, hex_color, description.
update_projectA
Update a project. Only the fields you pass change.
is_archived archives and unarchives, and Vikunja has no separate archive
endpoint. Archiving has two consequences worth knowing before using it. The
project drops out of list_projects unless that call is given
include_archived: true. And Vikunja then refuses every other edit to it, and to
the tasks in it, with a 412 naming the archive. Unarchive it before changing
anything else on it.
parent_project_id re-parents the project. Pass the id of the project it should
sit under. hex_color is six hex digits with no leading #, and an empty string
clears it. description is Markdown.
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.
Inputs: project_id (required), title, hex_color, description, +2 more.
update_taskA
Update a task. Only the fields you pass change. Use done to open/close it.
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.
due_date is the deadline. start_date and end_date are ISO 8601 datetimes
marking the window you plan to work on the task (start work / finish work).
Pass an empty string to any of the three to clear it.
percent_done is a fraction despite the name. A quarter done is 0.25. Vikunja
does not validate it, and 50 is stored as 50.
repeat_after is a number of seconds. Setting it changes what done means for
this task: it reopens itself with its dates moved forward. repeat_mode is 0 to
advance by repeat_after, 1 to repeat monthly and ignore repeat_after, or 2 to
count from the day it was completed. A repeating task with no dates can never be
closed: it reopens regardless.
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 get_task when you need
it as Markdown. And a write that changes nothing returns
{"ok": true, "unchanged": true} there, which is Vikunja answering 304.
Inputs: task_id (required), done, title, due_date, +8 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
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.
Maintenance
Related MCP Connectors
Official Todoist MCP server. Manage tasks and projects. Hosted, no API key needed.
MCP server for the Vulners.com API
MCP server wrapping the Tesla Fleet API and TeslaMate API
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceAn MCP server for managing your repositories on Forgejo/Gitea server.70Mozilla Public 2.0
- AlicenseAqualityBmaintenanceMCP server for TickTick — create, update, complete, move, and filter tasks (plus subtasks, completed-task retrieval, and recurring reminders) via the TickTick v2 API. Maintained fork of jen6/ticktick-mcp adding field-preserving updates, day-of-week date validation, completion tracking and more.141GPL 3.0
- AlicenseNot gradedqualityDmaintenanceLightweight MCP server for Vikunja task management, providing tools to manage projects, tasks, labels, and comments via API.43 npmMIT
- AlicenseNot gradedqualityDmaintenanceA security-hardened MCP server for TickTick that enables managing your tasks directly through any MCP-compatible client.16 PyPI1MIT