# Usage

This document provides instructions on how to add and use the Vikunja MCP server with the Gemini CLI.

## Prerequisites

Before adding the MCP server, you need to set the following environment variables:

```bash
export VIKUNJA_URL="<your_vikunja_url>"
export VIKUNJA_USERNAME="<your_vikunja_username>"
export VIKUNJA_PASSWORD="<your_vikunja_password>"
```

# MCP

## Adding the MCP Server

To add the Vikunja MCP server to the Gemini CLI, use the following command:

```bash
gemini mcp add --name vikunja --command "python main.py"
```

## Starting the MCP Server

To start the Vikunja MCP server, use the following command:

```bash
gemini mcp start vikunja
```

## Stopping the MCP Server

To stop the Vikunja MCP server, use the following command:

```bash
gemini mcp stop vikunja
```

## Removing the MCP Server

To remove the Vikunja MCP server from the Gemini CLI, use the following command:

```bash
gemini mcp remove vikunja
```

# Gemini CLI Extension

We now can run this with the Gemini CLI extension method which is far far easier to install.

Just use the following invokation:
```
$ gemini extensions install https://forgejo.freshbrewed.science/builderadmin/vikunjamcp
```

This should install the CLI and activate it:
```
$ gemini extensions install https://forgejo.freshbrewed.science/builderadmin/vikunjamcp
Installing extension "vikunja".
**Extensions may introduce unexpected behavior. Ensure you have investigated the extension source and trust the author.**
This extension will run the following MCP servers:
  * nodeServer (local): docker run -i --rm -e VIKUNJA_URL -e VIKUNJA_USERNAME -e VIKUNJA_PASSWORD harbor.freshbrewed.science/library/vikunjamcp:0.11
Do you want to continue? [Y/n]: Y
Extension "vikunja" installed successfully and enabled.
builder@DESKTOP-QADGF36:~/Workspaces/vikunjamcp$ gemini extensions list
✓ vikunja (1.0.11)
 Path: /home/builder/.gemini/extensions/vikunja
 Source: https://forgejo.freshbrewed.science/builderadmin/vikunjamcp (Type: git)
 Enabled (User): true
 Enabled (Workspace): true
 MCP servers:
  nodeServer
```

Because this does not hardcode a server, user or password, you'll want to set that before invoking Gemini, e.g.
```
$ export VIKUNJA_URL='https://vikunja.steeped.space'
$ export VIKUNJA_USERNAME='idjohnson'
$ export VIKUNJA_PASSWORD='xxxxxxxxxxxxxxxxxxxxxxx'
$ gemini
```

Personally, I now set those in my `~/.bashrc` (or zshrc if you use zshell).

When launched, this will launch it in Docker and you can use ctrl-t to see the tools

```
🟢 nodeServer (from vikunja) - Ready (5 tools)
  Tools:
  - add_task
    Adds a new task to a Vikunja project.

    :param project_id: The ID of the project to add the task to.
    :param title: The title of the new task.
    :param description: An optional description for the task.
  - close_task
    Closes (marks as done) a task in Vikunja.

    :param task_id: The ID of the task to close.
  - login
    Authenticates with the Vikunja API to get a session token.
  - lookup_project
    Retrieves all projects the user has access to and lists them by name and ID.
  - search_tasks
    Searches for tasks in Vikunja.

    :param query: The search string to use for finding tasks.
```