Skip to main content
Glama

Altiplano

Altiplano

CI codecov Python PyPI version License Altiplano MCP server

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 uvx

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 uvx and communicates over stdio.

Connects to the service URL with a valid bearer token.

Requirements on your computer

uv, Python 3.10 or later, and an MCP client supporting stdio.

An MCP client supporting Streamable HTTP and a configured Authorization header.

Where the Vikunja credentials live

On each computer running Altiplano.

On the service host, one token per client.

Setup

Use locally

Use over HTTP

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/altiplano

Create ~/.config/altiplano/env containing:

VIKUNJA_URL=https://altiplano.example.com/api/v2
VIKUNJA_API_TOKEN=tk_replace_me

Restrict the file's permissions:

chmod 600 ~/.config/altiplano/env

Altiplano checks these sources in order:

  1. The VIKUNJA_URL and VIKUNJA_API_TOKEN environment variables.

  2. A file containing KEY=VALUE pairs, 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_URL must end in /api/v1 or /api/v2. That suffix selects the version, for example https://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/v2 when the server supports it.

Permissions broader than 600 produce 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 altiplano checks PyPI for a current release. If an older version still starts, close the client and run uv 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 altiplano in 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 with 403.

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 value streamable-http and others http, some call the key transport, and some infer the transport from url alone. 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: Bearer challenge and publishes no OAuth metadata. A client may still probe the well-known metadata URLs on its own initiative and will get a 404. A client that can only obtain credentials through an OAuth flow is not supported here.

Tools

  • list_projects(include_archived=False): includes parent_project_id for sub-projects and is_archived. Vikunja omits archived projects from this endpoint; include_archived=True adds them back alongside the active ones.

  • create_project(title, parent_project_id?, description?): pass parent_project_id to 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_archived archives and unarchives, and Vikunja has no separate archive endpoint. hex_color is 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 prefer update_project(project_id, is_archived=True) to set a project aside.

Archiving hides a project from list_projects unless include_archived=True. Vikunja also refuses every other edit to an archived project, and to the tasks in it, with a 412. Unarchive it first.

  • list_tasks(project_id, filter?, sort_by?, page=1, per_page=50): Vikunja applies filter and sort_by before pagination.

  • search_tasks(query?, filter?, sort_by?, page=1, per_page=50): searches all visible projects and includes project_id in each result. Vikunja does not combine text search with filter.

  • 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 for due_date, start_date, or end_date to clear it.

  • move_task(task_id, project_id): moves labels, assignees, comments, relations, and dates with the task. The destination project assigns a new local identifier.

  • duplicate_task(task_id): copies the task, labels, assignees, attachments, and reminders into the same project. The copy receives a copiedfrom relation 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 as create_task, title included, 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. Omit limit, or pass 0, 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_count remains the full count when Vikunja caps the returned task list. Takes the same arguments as list_buckets and 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". Without view_id, Altiplano uses the first kanban view in the project's view order.

  • bucket_configuration_mode="manual" accepts explicit moves. In filter mode, 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 done to true through update_task moves 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_task returns related_tasks, grouped by kind. Supported kinds are subtask, parenttask, related, duplicateof, duplicates, blocking, blocked, precedes, follows, copiedfrom, and copiedto.

add_relation(task_id, other_task_id, "subtask") makes other_task_id a child of task_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_color is six hexadecimal digits without #. update_label changes 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_comment replaces the complete text. Get comment_id from list_comments.

search_users(query), list_assignees(task_id), add_assignee(task_id, user_id), remove_assignee(task_id, user_id).

Use search_users to find the user_id required 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_guide prompt holds the full version, with cross-tool sequencing and the v1 and v2 differences. Clients list it as Using Altiplano.

  • AGENTS.md covers working on this repository, and installing Altiplano for someone else. CLAUDE.md imports it, for Claude Code.

  • DEPLOYMENT.md covers running the HTTP transport as a service on a host: Docker with a Dockerfile and a compose file, a two-command uv path 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: 0 Unset, 1 Low, 2 Medium, 3 High, 4 Urgent, and 5 DO NOW.

  • Dates are ISO 8601 datetimes. start_date and end_date define the work window; due_date is the deadline.

  • An empty string clears a date by writing Vikunja's zero time, 0001-01-01T00:00:00Z.

  • percent_done is a fraction. A quarter complete is 0.25. Vikunja does not clamp the value, and 50 remains 50.

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 by repeat_after.

  • 1: repeat monthly and ignore repeat_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/bulk cleared 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_tasks reads the server's release once from /info and refuses below 2.7.1.

  • On Vikunja 2.5.0, the v2 grouped-bucket route used by list_board may 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_buckets reads a different route and is unaffected.

  • On Vikunja 2.3.0, list_assignees returns 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 tools
add_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

    B3.4/5.0

    Scored across 39 tools

    Disambiguation4/5

    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.

    Naming Consistency5/5

    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.

    Tool Count3/5

    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).

    Completeness4/5

    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

    ActivityNo data
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      B
      maintenance
      MCP 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.
      14
      1
      GPL 3.0