Altiplano

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

Requires Python 3.10 or later.

Tools

Credentials

Altiplano checks these sources in order:

1. 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 use another file. Use an absolute path; ~ is not expanded in custom paths.

VIKUNJA_URL must include the API prefix, such as https://todo.example.com/api/v2.

Vikunja 2.4.0 introduced /api/v2. VIKUNJA_URL should end in /api/v1 or /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.

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

Permissions broader than 600 produce a warning (on POSIX) but do not prevent startup. An unreadable file is ignored after a warning.

MCP server entry (without credentials):

{
  "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 MCP client and run:

uv cache clean altiplano

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, so 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.

Identified issues:

• On Vikunja 2.5.0, the v2 grouped-bucket route used by list_bucket_tasks 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, so verify the token itself too.
• On Vikunja 2.3.0, list_assignees returns HTTP 500. The endpoint worked on 2.5.0.

Contributing

Enable the pre-commit hook once per clone:

git config core.hooksPath hooks

The hook runs Ruff 0.16.4 over src and tests, then pytest with a 90 percent coverage minimum. CI runs Ruff in one job and pytest on Python 3.10 and 3.13.

Run

uv run altiplano                                      # development checkout
uvx --from /your/local/path altiplano                 # local package path
uvx --refresh-package altiplano altiplano@latest      # current PyPI release

Layout

src/altiplano/
  app.py       MCP instance imported by the tool modules
  config.py    Credential resolution and credential-file parsing
  api.py       API-version handling, requests, and response shaping
  tools/       One module for each tool group
  server.py    Tool registration and the main entry point

Register a tool group by adding its module and importing it from server.py. Add its tools to the routing-table test and the smoke test's exact list.

Pull requests are always welcome!

Licence

MIT.

Support

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