Altiplano

Altiplano

A small, dependable MCP server for Vikunja. Named after the Andean altiplano, the high plateau that is the Vicuña's native habitat.

Filtering and sorting are passed straight to the Vikunja API (server-side), so there is no client-side filtering engine and no paginate-then-filter pitfall.

Tools

Projects:

• list_projects (includes parent_project_id, shows sub-project nesting)
• create_project (title, parentprojectid?, description?) — pass parent_project_id for a sub-project

Tasks:

• list_tasks (projectid, filter, sortby, page, per_page)
• get_task (task_id)
• create_task (projectid, title, description?, priority?, duedate?, startdate?, enddate?)
• update_task (taskid, title?, description?, done?, priority?, startdate?, end_date?)
• set_reminders (task_id, reminders) — replaces the task's reminders with the given ISO 8601 datetimes; empty list clears

Labels:

• list_labels
• add_label (taskid, labelid)
• remove_label (taskid, labelid)

Comments:

• list_comments (task_id)
• add_comment (task_id, comment)

Assignees:

• search_users (query) — find a user_id to assign
• list_assignees (task_id)
• add_assignee (taskid, userid)
• remove_assignee (taskid, userid)

Credentials (no secrets in mcp.json)

The server resolves two values, in order:

1. Environment variables VIKUNJA_URL and VIKUNJA_API_TOKEN.
2. A per-device file of KEY=VALUE lines, default ~/.config/altiplano/env

(override the path with ALTIPLANO_CONFIG).

VIKUNJA_URL is the base API URL including /api/v1 (e.g. https://todo.example.com/api/v1).

Recommended so the your mcp.json carries no secrets:

• Drop a per-device file and lock it down:

``bash mkdir -p ~/.config/altiplano printf 'VIKUNJA_URL=https://todo.example.com/api/v1\nVIKUNJA_API_TOKEN=tk_xxx\n' > ~/.config/altiplano/env chmod 600 ~/.config/altiplano/env ``

• Or inject via the launcher's environment (e.g. a systemd unit EnvironmentFile= pointing at a chmod 600 file), which the server inherits.
• For stronger setups, source the token from a secret manager/keychain at launch and export it into the environment.

Then mcp.json only needs the command, no env block, no plain-text secrets:

{
  "altiplano": {
    "command": "uvx",
    "args": ["altiplano"]
  }
}

Run

uv run altiplano                        # dev, from this directory
uvx --from /your/local/path altiplano   # local path
uvx altiplano                           # from PyPI

Notes

• Vikunja priority scale: 0 Unset, 1 Low, 2 Medium, 3 High, 4 Urgent, 5 DO NOW.
• Dates are ISO 8601 datetimes. start_date/end_date mark the window you plan to work on a task (start work / finish work); due_date is the deadline.
• The UI shows tasks by their project-local identifier (e.g. #50), which is not the global id the API uses.
• Endpoint shapes (create via PUT /projects/{id}/tasks, update via POST /tasks/{id}) follow current Vikunja; adjust if your instance differs.

Licence

[MIT](./LICENSE).

Support

RTFM, then RTFC... If you are still stuck or just need an additional feature, file an issue.

✌🏼

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: aichholzer
• Source: aichholzer/altiplano
• License: MIT

Install and usage instructions live in the source repository linked above.