vikunja-python 0.1.1

API wrapper, CLI tool, and MCP server for Vikunja

Vikunja Python

Python API wrapper, CLI tool, MCP server, and Home Assistant integration for the Vikunja task management system.

Built for Python 3.13 with httpx, pydantic v2, fastmcp, and typer.

Architecture

The project is structured into layers:

• core/ -- Pydantic models, async HTTP client (httpx), error handling, API token and JWT authentication
• cli/ -- Rich CLI built with typer and rich (task CRUD, project views, saved filter queries, dashboard summary)
• mcp/ -- MCP server for agentic AI workflows (13 tools including list_tasks, get_task, create_task, list_saved_filter, task_summary)
• custom_components/vikunja/ -- Home Assistant HACS integration (config flow, 3 sensors for saved filters)

Getting Started

Installation

From PyPI:

pip install vikunja-python

Or with uv:

uv sync --all-extras

Environment Variables

Configure your Vikunja instance in a .env file or your shell:

VIKUNJA_URL="https://your-vikunja-instance.com/api/v1"
VIKUNJA_API_TOKEN="your_api_token_here"
VIKUNJA_DEBUG="true"   # Enable verbose stderr logging

Features

CLI (vikunja)

The CLI provides a human-friendly interface for managing tasks:

• list-tasks -- List tasks with rich table output (supports saved filters via negative project IDs)
• list-saved-filter -- Query saved filters (e.g., -2 for Due in 3 Days, -3 for Overdue, -4 for Due Today)
• summary -- Quick dashboard summary across all saved filters (parallel queries, optimized for ePaper dashboards)
• get-project -- Project details and views
• list-view-tasks -- List tasks from a specific project view
• get-task -- Full task details with description
• create-task -- Create a new task
• create-label -- Create a new label

uv run vikunja list-tasks
uv run vikunja list-saved-filter --filter-id -2
uv run vikunja summary --top 5

MCP Server (vikunja-mcp)

MCP server for agentic workflows. 13 tools including:

• list_tasks, get_task, create_task, update_task, complete_task, delete_task
• list_saved_filter -- Query saved filters (e.g., -2 for Due in 3 Days)
• task_summary -- Dashboard summary across all filters in one parallel call
• list_projects, get_project, list_project_view_tasks
• list_labels, create_label
• add_subtask, add_task_link

uv run vikunja-mcp

Home Assistant Integration

The package includes a HACS-ready custom component for Home Assistant:

• Config flow: URL + API token via the HA UI
• 3 sensors: Overdue, Due Today, Due in 3 Days (from Vikunja saved filters)
• Each sensor: state = task count, attributes = task list with IDs, titles, due dates
• Coordinator polls all filters in parallel every 5 minutes

Copy custom_components/vikunja/ to your HA config's custom_components/ directory, restart HA, and add via Settings -> Devices & Services.

Saved Filter Support

Vikunja saved filters are accessed via negative project IDs:

ID	Filter
-2	Due in 3 Days
-3	Overdue
-4	Due Today

The API route is GET /tasks?project_id=-2 (NOT /projects/-2/tasks).

Testing

Unit tests run without Docker:

uv run pytest tests/test_task_models_unit.py tests/test_label_model_validation.py -v

Integration tests require Docker (spins up a real Vikunja instance via testcontainers):

uv run pytest

Security & Auth

• API Key auth is the primary authentication method for both CLI and MCP server
• JWT tokens are used for UI-specific features (kanban buckets, reactions) in the CLI only
• The MCP server only supports API key authentication

License

WTFPL - Do What the Fuck You Want to Public License.