# vikunja-mcp

An [MCP](https://modelcontextprotocol.io) server that bridges Claude (or any MCP client) to a self-hosted [Vikunja](https://vikunja.io) instance. Exposes projects, tasks, labels, and comments as tools the model can call over stdio.

## Requirements

- Node.js >= 18
- A Vikunja instance and an API token

## Install

```bash
npm install
npm run build
```

## Configuration

The server reads its config from environment variables, falling back to a dotenv-style file (default `~/.vikunja-env`, override with `VIKUNJA_ENV_FILE`).

| Variable | Required | Default | Description |
| --- | --- | --- | --- |
| `VIKUNJA_API_TOKEN` | yes | — | Vikunja API token (also accepts `API_TOKEN` in the env file) |
| `VIKUNJA_SERVICE_URL` | yes | — | Base URL of the Vikunja API (also accepts `SERVICE_URL`) |
| `VIKUNJA_DEFAULT_PROJECT_ID` | no | `1` | Project used when none is specified |
| `VIKUNJA_ENV_FILE` | no | `~/.vikunja-env` | Path to the env file |

Example `~/.vikunja-env`:

```
VIKUNJA_API_TOKEN=tk_xxxxxxxxxxxxxxxx
VIKUNJA_SERVICE_URL=https://vikunja.example.com/api/v1
VIKUNJA_DEFAULT_PROJECT_ID=1
```

> **Note:** Never commit your token. Keep it in `~/.vikunja-env` or your MCP client's env config — both are outside the repo.

## Usage with Claude

Add to your MCP client config (e.g. Claude Desktop `claude_desktop_config.json`):

```json
{
  "mcpServers": {
    "vikunja": {
      "command": "node",
      "args": ["/absolute/path/to/vikunja-mcp/dist/index.js"],
      "env": {
        "VIKUNJA_API_TOKEN": "tk_xxxxxxxxxxxxxxxx",
        "VIKUNJA_SERVICE_URL": "https://vikunja.example.com/api/v1"
      }
    }
  }
}
```

## Tools

**Diagnostics:** `check_connection`, `debug_defaults`

**Projects:** `list_projects`, `get_project`, `create_project`, `update_project`, `archive_project`

**Tasks:** `get_tasks`, `get_task`, `create_task`, `update_task`, `complete_task`, `delete_task`, `plan_tasks_for_today`

**Labels:** `list_labels`, `create_label`, `add_label_to_task`, `remove_label_from_task`

**Comments:** `list_comments`, `create_comment`, `delete_comment`

## Development

```bash
npm run dev        # tsup watch build
npm run typecheck  # tsc --noEmit
npm run build      # production build to dist/
```

## License

MIT — see [LICENSE](LICENSE).