Skip to content

USAGE.md

Latest commit

 

History

History
110 lines (82 loc) · 3.13 KB

USAGE.md

File metadata and controls

110 lines (82 loc) · 3.13 KB

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:

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:

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

Starting the MCP Server

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

gemini mcp start vikunja

Stopping the MCP Server

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

gemini mcp stop vikunja

Removing the MCP Server

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

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.