Vikunja MCP für Codex

Verwenden Sie normale Sätze in Codex, um Aufgaben in Ihrem eigenen Vikunja-Konto zu lesen und zu verwalten.

Sie können Codex zum Beispiel fragen:

Show my open Vikunja tasks.
Create a task called "Prepare the launch checklist" in my Website Redesign project.
Mark task 42 as complete.

Sie müssen keine /-Befehle eingeben oder das Plugin mit @ erwähnen. Fragen Sie nach der Installation auf natürliche Weise in einer neuen Codex-Aufgabe.

Warum dieses Plugin existiert

Vikunja und Codex sprechen von sich aus nicht dieselbe Sprache:

• Vikunja bietet eine HTTP-API für Projekte und Aufgaben.

• Codex verwendet MCP-Tools, wenn es mit einer anderen Anwendung zusammenarbeiten muss.

• Dieses Plugin ist die kleine Brücke, die die MCP-Anfragen von Codex in Vikunja-API-Anfragen übersetzt.

You → Codex → this plugin → your Vikunja API → your tasks

Das Plugin ersetzt weder Vikunja, noch hostet es eine zweite Aufgabendatenbank oder greift direkt auf die Vikunja-Datenbank zu. Vikunja behält die Kontrolle über Anmeldungen, Berechtigungen, Validierung und Speicherung.

Related MCP server: Vikunja MCP Server

Was es kann

• Vikunja-Projekte auflisten und erstellen.

• Aufgaben in einem Projekt auflisten.

• Aufgaben erstellen und aktualisieren.

• Aufgaben als erledigt markieren.

Löschvorgänge sind in dieser ersten Version bewusst nicht enthalten.

Installation für Einsteiger

Diese Anleitung ist für jemanden, der zum ersten Mal einen neuen Computer mit Codex einrichtet.

1. Die Codex-CLI installieren

Die Terminalbefehle in dieser Anleitung benötigen die Codex-CLI, auch wenn Sie die Codex-Desktop-App verwenden.

Verwenden Sie unter macOS oder Linux das offizielle Installationsprogramm:

curl -fsSL https://chatgpt.com/codex/install.sh | sh

Für Windows und alternative Installationsmethoden folgen Sie der offiziellen Codex-CLI-Anleitung.

Öffnen Sie ein neues Terminal, bestätigen Sie die Installation und melden Sie sich an:

codex --version
codex

Wenn das Terminal codex: command not found meldet, schließen und öffnen Sie das Terminal zuerst erneut. Wenn es immer noch fehlschlägt, kehren Sie zur offiziellen Installationsanleitung zurück und überprüfen Sie, ob das Codex-Installationsverzeichnis in Ihrem PATH ist.

2. Node.js und Git installieren

Installieren Sie:

• Node.js Version 20 oder neuer. Wählen Sie die aktuelle LTS-Version, es sei denn, Sie haben einen Grund dagegen.

• Git, das bei der Installation direkt von GitHub verwendet wird.

Die Installation von Node.js installiert auch npm und npx. Überprüfen Sie alles in einem neuen Terminal:

node --version
npm --version
npx --version
git --version

Sie müssen npm install für die normale Nutzung nicht ausführen. Der fertige MCP-Server und seine Abhängigkeiten sind bereits in diesem Repository gebündelt.

3. Das Plugin von GitHub installieren

Dieses Repository muss unter DanJamesMills/vikunja-mcp öffentlich sein, damit diese Befehle für andere Personen funktionieren.

Fügen Sie das GitHub-Repository als Codex-Plugin-Marktplatz hinzu:

codex plugin marketplace add DanJamesMills/vikunja-mcp --ref main

Installieren Sie das Vikunja-Plugin daraus:

codex plugin add codex-vikunja@vikunja-mcp

Bestätigen Sie, dass Codex es sehen kann:

codex plugin list

Sobald der Marktplatz hinzugefügt wurde, kann das Plugin auch im Plugin-Verzeichnis der Codex-Desktop-App angezeigt und verwaltet werden.

4. Ein Vikunja-API-Token erstellen

Melden Sie sich auf Ihrer eigenen Vikunja-Website an und öffnen Sie:

Einstellungen → API-Tokens

Erstellen Sie ein dediziertes Token mit den Lese- und Schreibberechtigungen, die Codex haben soll. Kopieren Sie es, während Vikunja es anzeigt.

5. Das Plugin mit Vikunja verbinden

Führen Sie die geführte Einrichtung aus:

npx --yes github:DanJamesMills/vikunja-mcp setup

Es fragt nach:

1. Ihrer Vikunja-URL, z. B. https://tasks.example.com.

2. Ihrem Vikunja-API-Token. Die Tokeneingabe ist verborgen.

Die Einrichtung überprüft die Verbindung, bevor sie gespeichert wird. Jeder Benutzer gibt seine eigene URL und sein eigenes Token ein; dieses öffentliche Repository enthält keines von beidem.

npx lädt lediglich den Einrichtungsbefehl aus diesem GitHub-Repository herunter und führt ihn aus. Es ist in Node.js enthalten, daher gibt es keine separate npx-Installation.

6. Codex neu starten und testen

Schließen und öffnen Sie Codex oder starten Sie eine neue Codex-Aufgabe, damit der neu installierte MCP-Server geladen wird. Fragen Sie dann:

List my Vikunja projects.

Versuchen Sie danach einen Schreibvorgang:

Create a task called "Test the Vikunja Codex plugin" in project 12.

Das ist die vollständige Einrichtung für normale Benutzer.

Funktioniert es nach einem Neustart noch?

Ja. Die Einrichtung speichert die URL und das Token im Ordner für Benutzeranwendungsdaten Ihres Betriebssystems. Wenn Codex das Plugin erneut startet, liest es dieselbe Datei automatisch.

Die Einstellungen überleben auch Plugin-Updates. Sie müssen das Token nicht erneut exportieren, nachdem Sie Ihr Terminal, Codex oder den Computer neu gestartet haben.

Gespeicherte Verbindung prüfen, ändern oder entfernen

Verwenden Sie jederzeit diese Befehle:

npx --yes github:DanJamesMills/vikunja-mcp status
npx --yes github:DanJamesMills/vikunja-mcp configure
npx --yes github:DanJamesMills/vikunja-mcp logout

• status zeigt an, ob Einstellungen vorhanden sind, zeigt aber niemals das Token an.

• configure überprüft und speichert eine andere URL oder ein anderes Token.

• logout fragt nach Bestätigung und entfernt die gespeicherten Einstellungen.

Nachdem Sie die Verbindung geändert oder entfernt haben, starten Sie Codex neu oder öffnen Sie eine neue Aufgabe. Das Entfernen der gespeicherten Verbindung ist getrennt von der Deinstallation des Plugins selbst. Um sowohl die gespeicherte Verbindung als auch das installierte Plugin zu entfernen, führen Sie Folgendes aus:

npx --yes github:DanJamesMills/vikunja-mcp logout
codex plugin remove codex-vikunja@vikunja-mcp

Das Plugin kann auch über das Codex-Plugin-Verzeichnis deinstalliert werden.

Wo die Einstellungen gespeichert werden

• macOS: ~/Library/Application Support/vikunja-mcp/config.json

• Windows: %APPDATA%\vikunja-mcp\config.json

• Linux: $XDG_CONFIG_HOME/vikunja-mcp/config.json oder ~/.config/vikunja-mcp/config.json

Die JSON-Datei enthält die Vikunja-URL und das API-Token im Klartext. Unter macOS und Linux wendet die Einrichtung Berechtigungen nur für den Besitzer des Verzeichnisses und der Datei an (0700 und 0600). Unter Windows erbt die Datei die Berechtigungen des aktuellen Benutzers für Anwendungsdaten.

Schützen Sie Ihr Betriebssystemkonto, erstellen Sie ein dediziertes Vikunja-Token mit nur den benötigten Berechtigungen und übergeben Sie niemals ein echtes Token oder fügen Sie es in ein öffentliches Issue ein. Siehe SECURITY.md.

Frühe Testversionen verwendeten die macOS-Tastatur. Das Ausführen von setup oder logout bereinigt auch diesen alten Testeintrag.

Mehrere Vikunja-Installationen

Das öffentliche Plugin funktioniert mit selbst gehostetem Vikunja und Vikunja Cloud, da jeder Benutzer seine eigene URL und sein eigenes Token bereitstellt.

Diese Version unterstützt eine aktive Vikunja-Installation pro Computer. Führen Sie configure aus, um zu einer anderen Installation zu wechseln.

Optionale Umgebungsvariablen

Fortgeschrittene Benutzer und Server können Einstellungen ohne die Einrichtungsdatei bereitstellen:

• VIKUNJA_URL

• VIKUNJA_API_TOKEN

Umgebungsvariablen überschreiben die gespeicherten Einstellungen. Die URL kann entweder https://tasks.example.com oder https://tasks.example.com/api/v1 sein; das Plugin normalisiert beide Formen.

macOS und Linux

export VIKUNJA_URL="https://tasks.example.com"
export VIKUNJA_API_TOKEN="tk_your_token"
codex

Windows PowerShell

$env:VIKUNJA_URL = "https://tasks.example.com"
$env:VIKUNJA_API_TOKEN = "tk_your_token"
codex

In einem Terminal exportierte Variablen verschwinden normalerweise, wenn das Terminal geschlossen wird. Die geführte Einrichtung ist für die Desktop-Nutzung einfacher, da ihre Einstellungen Neustarts überdauern.

Das Plugin aktualisieren

Rufen Sie die neuesten Marktplatzinformationen von GitHub ab:

codex plugin marketplace upgrade vikunja-mcp

Installieren Sie dann das verfügbare Vikunja-Update aus dem Plugin-Verzeichnis oder führen Sie den Plugin-Installationsbefehl erneut aus:

codex plugin add codex-vikunja@vikunja-mcp

Starten Sie nach dem Update eine neue Codex-Aufgabe. Für Produktionsversionen ist die Installation aus einem getaggten Git-Release sicherer als die Verwendung von main, da die Version festgelegt ist.

Enthaltene MCP-Tools

• vikunja_list_projects

• vikunja_create_project

• vikunja_list_tasks

• vikunja_create_task

• vikunja_update_task

• vikunja_complete_task

Die meisten Benutzer benötigen diese Namen nie; sie sind die internen Tools, die Codex basierend auf Ihrer natürlichsprachlichen Anfrage auswählt.

Für Mitwirkende

Nur Mitwirkende, die den Plugin-Quellcode ändern, müssen das Repository klonen und seine Entwicklungsabhängigkeiten installieren:

git clone https://github.com/DanJamesMills/vikunja-mcp.git
cd vikunja-mcp
npm install
npm test
npm run build

Committen Sie das neu erstellte mcp/server.bundle.mjs, wenn sich der Quellcode oder die Abhängigkeiten ändern. Installierte Benutzer führen dieses Bundle aus, daher benötigen sie kein lokales node_modules-Verzeichnis.

Testen Sie das Onboarding-Bundle aus einem geklonten Checkout:

node mcp/server.bundle.mjs setup
node mcp/server.bundle.mjs status
node mcp/server.bundle.mjs logout

Führen Sie die Konfigurationsprüfung mit temporären Werten durch:

VIKUNJA_URL="https://tasks.example.com" \
VIKUNJA_API_TOKEN="tk_test_token" \
npm run check

Die Tokeneingabe ist verborgen. Setzen Sie niemals ein echtes Token in ein Befehlsargument, eine Testumgebung, die Terminal-Historie oder einen Git-Commit.

Beginnen Sie mit docs/FOLDER-GUIDE.md, um zu erfahren, was jede Datei tut und wie eine Anfrage durch das Plugin läuft.

npm-Veröffentlichung

Das Paket ist als private markiert, um eine versehentliche Veröffentlichung auf npm zu verhindern. Die GitHub-Installation verwendet das gebündelte Bundle und erfordert kein npm-Paket.

Wenn dieses Projekt später auf npm veröffentlicht wird, wählen und sichern Sie einen Paketnamen, entfernen Sie private, fügen Sie eine Release-Automatisierung hinzu, prüfen Sie Abhängigkeiten und veröffentlichen Sie unveränderliche Versionen.