Zum Inhalt springen
Kanroo
AnmeldenKostenlos starten

KI-Agenten per MCP verbinden

AnleitungAktualisiert am

Auf dieser Seite

Kanroo enthält einen Server für das Model Context Protocol (MCP). Ein KI-Agent wie Claude Code, Codex oder Cursor kann damit Deine Boards, Aufgaben, Kommentare, Checklisten und Wiki-Seiten lesen und ändern. Der Agent arbeitet mit Deinem persönlichen API-Schlüssel. Er darf also nur, was Dein Konto darf.

Für die Verbindung gibt es zwei Wege:

  • Remote-Endpunkt. Deine Kanroo-Adresse mit angehängtem /mcp. Du musst nichts installieren. Nutze diesen Weg im Normalfall.
  • Lokaler Server. Ein kleines Programm, das Du aus dem Kanroo-Repository baust und auf Deinem Computer ausführst. Nutze ihn, wenn der Agent Dateien verarbeiten muss, aber keine Shell-Befehle ausführen kann.

Beide bieten dieselben Tools. Nur bei Dateien gibt es einen Unterschied: Der lokale Server hat die Datei-Tools, der Remote-Endpunkt hat stattdessen das Tool get_file_transfer. Siehe Dateien.

Schnellstart

In drei Schritten verbindest Du Claude Code über den Remote-Endpunkt mit Kanroo Cloud. Codex, Cursor, ein selbst gehostetes Kanroo und der lokale Server folgen weiter unten.

Schritt 1: Schlüssel erstellen

Folge der Anleitung API-Schlüssel erstellen. Für den Agenten gilt:

  • Benenne den Schlüssel nach dem Agenten, zum Beispiel „Claude Code (MCP)“.
  • Wähle den kleinsten Scope, den der Agent braucht. Der Scope legt fest, welche Tools der Agent bekommt (siehe Scopes der API-Schlüssel).

Schritt 2: Kanroo zum Agenten hinzufügen

Für Claude Code und Kanroo Cloud führst Du diesen Befehl aus:

claude mcp add --scope user --transport http kanroo https://cloud.kanroo.app/mcp --header "Authorization: Bearer <api-key>"

Ersetze <api-key> durch Deinen Schlüssel. Wie Du Codex, Cursor oder ein selbst gehostetes Kanroo verbindest, steht unter Mit dem Remote-Endpunkt verbinden.

Schritt 3: Ausprobieren

Starte den Agenten und frage: „Rufe get_context auf und liste meine Kanroo-Boards auf.“ Gib ihm dann echte Arbeit, zum Beispiel „Was steht heute auf meiner Agenda?“ oder „Lege im Backlog eine Aufgabe für den Text des Cookie-Banners an.“

Scopes der API-Schlüssel

Jeder persönliche API-Schlüssel hat genau einen Scope (Berechtigungsumfang):

Scope Tools
Lesen Boards, Board-Vorlagen, Aufgaben, Kommentare, Aktivitäten, Importe, Wiki-Seiten, Teams und Zugriffsfreigaben lesen sowie Boards und Wiki-Spaces exportieren.
Schreiben Alles aus „Lesen“, dazu anlegen, ändern, verschieben und löschen, auch Wiki-Spaces.
Admin Alles aus „Schreiben“, dazu Mitglieder, Einladungen, Änderungen an Teams, Änderungen an Zugriffen, Eigentümerschaft von Wiki-Spaces und alles Öffentliche: Sichtbarkeit von Boards, Veröffentlichung von Aufgaben und Freigaben.

Der Agent sieht nur die Tools, die der Scope seines Schlüssels erlaubt. Wähle den kleinsten Scope, den der Agent braucht.

Ein Schlüssel darf nie mehr als Deine Rolle. Jeder Aufruf prüft weiterhin Deine aktuellen Rollen und Deinen Zugriff auf das Board. Ein Admin-Schlüssel gibt keinen Zugriff auf Boards, die Du selbst nicht öffnen kannst.

Dieselben Scopes gelten, wenn Du die REST-API direkt aufrufst. Den Scope jedes Endpunkts nennt die API-Referenz. Das ist das OpenAPI-Dokument im Kanroo-Repository oder /api/docs, wenn Deine Instanz diese Seite bereitstellt.

Mit dem Remote-Endpunkt verbinden

Die Adresse des Endpunkts ist Deine Kanroo-Adresse mit angehängtem /mcp:

  • Kanroo Cloud: https://cloud.kanroo.app/mcp
  • Selbst gehostet: https://<your Kanroo domain>/mcp

Der Agent sendet den Schlüssel im Header Authorization: Bearer <api-key>. Ersetze in den Beispielen unten <api-key> durch Deinen Schlüssel.

Claude Code

claude mcp add --scope user --transport http kanroo https://cloud.kanroo.app/mcp --header "Authorization: Bearer <api-key>"

--scope user speichert den Server in Deiner persönlichen Claude-Code-Konfiguration. So funktioniert er in jedem Verzeichnis. Ohne diese Option gilt der Server nur im aktuellen Verzeichnis. Nutze nicht --scope project: Damit landet der Schlüssel in <project>/.mcp.json, und diese Datei wird meist committet. Führe claude mcp get kanroo aus, starte Claude Code, öffne /mcp und bitte Claude Code, get_context aufzurufen. Mehr dazu steht in der MCP-Dokumentation von Claude Code.

Codex

Exportiere den Schlüssel als KANROO_API_KEY in der Umgebung, die Codex startet. Füge dann Folgendes in ~/.codex/config.toml ein:

[mcp_servers.kanroo]
url = "https://cloud.kanroo.app/mcp"
bearer_token_env_var = "KANROO_API_KEY"

Starte Codex neu, öffne /mcp und bitte Codex, get_context aufzurufen. Mehr dazu steht in der MCP-Dokumentation von Codex.

Cursor

Füge Folgendes in Deine persönliche Datei ~/.cursor/mcp.json ein:

{
    "mcpServers": {
        "kanroo": {
            "url": "https://cloud.kanroo.app/mcp",
            "headers": {
                "Authorization": "Bearer <api-key>"
            }
        }
    }
}

Starte Cursor neu, öffne Settings > Tools & MCP, aktiviere kanroo und bitte den Cursor-Agenten, get_context aufzurufen. Mehr dazu steht in der MCP-Dokumentation von Cursor.

Lokalen Server betreiben

Der lokale Server läuft auf Deinem Computer mit Node.js 24 unter Linux oder macOS. Windows wird nicht unterstützt. Es gibt ihn nicht als npm-Paket. Baue ihn aus einem Checkout des Kanroo-Repositorys:

pnpm install
pnpm --filter @kanroo/mcp --fail-if-no-match run build

Der Build erzeugt packages/mcp/dist/cli.js. Dein Agent startet die Datei mit Node.js und übergibt diese Umgebungsvariablen:

Variable Anforderung
KANROO_BASE_URL Deine Kanroo-Adresse, zum Beispiel https://cloud.kanroo.app. Für alle Hosts außer Deinem eigenen Computer ist HTTPS Pflicht. Ohne Benutzername, Passwort, Query und Fragment.
KANROO_API_KEY Dein persönlicher API-Schlüssel.
KANROO_FILES_ROOT Optional. Absoluter Pfad zu einem vorhandenen Ordner, den der Server lesen und beschreiben darf. Der Ordner muss Dir gehören, und nur Du darfst in ihn schreiben. Die Variable schaltet die Datei-Tools ein.

Die Datei-Tools akzeptieren nur relative Pfade innerhalb von KANROO_FILES_ROOT. Pfade, die den Ordner verlassen, auch über symbolische Links, werden abgelehnt. Der Ordner und jeder Unterordner, den ein Tool nutzt, müssen Dir gehören und dürfen für Deine Gruppe und für andere nicht beschreibbar sein. Sonst könnte ein anderer Benutzer ein Datei-Tool umlenken. Die Rechte eines Ordners korrigierst Du mit chmod go-w <folder>. Mit umask 002 sind neue Ordner für die Gruppe beschreibbar: Führe chmod go-w für sie aus oder nutze umask 022. Trifft ein Tool auf einen solchen Ordner, antwortet es mit „The local path is invalid.“ Verletzt KANROO_FILES_ROOT selbst die Regel, startet der Server nicht. Die Prüfung berücksichtigt nur den Eigentümer und die Rechte-Bits. Lege den Ordner nicht dorthin, wo ACLs (unter macOS mit ls -le prüfen und mit chmod -N entfernen) oder ein Netzwerk- oder Freigabelaufwerk anderen Benutzern das Schreiben erlauben. Uploads und Importe lesen nur reguläre Dateien.

Claude Code

claude mcp add-json --scope user kanroo '{
  "type": "stdio",
  "command": "node",
  "args": ["/absolute/path/to/kanroo/packages/mcp/dist/cli.js"],
  "env": {
    "KANROO_BASE_URL": "https://cloud.kanroo.app",
    "KANROO_API_KEY": "<api-key>",
    "KANROO_FILES_ROOT": "/absolute/path/to/allowed-files"
  }
}'

Codex

Exportiere die drei Variablen in der Umgebung, die Codex startet, und füge dann Folgendes hinzu:

[mcp_servers.kanroo]
command = "node"
args = ["/absolute/path/to/kanroo/packages/mcp/dist/cli.js"]
env_vars = ["KANROO_BASE_URL", "KANROO_API_KEY", "KANROO_FILES_ROOT"]
startup_timeout_sec = 45
tool_timeout_sec = 300

Setze startup_timeout_sec auf mehr als 30. Der Server wartet bis zu 30 Sekunden auf Kanroo, bevor er meldet, warum er nicht starten kann.

Cursor

{
    "mcpServers": {
        "kanroo": {
            "command": "node",
            "args": ["/absolute/path/to/kanroo/packages/mcp/dist/cli.js"],
            "env": {
                "KANROO_BASE_URL": "https://cloud.kanroo.app",
                "KANROO_API_KEY": "<api-key>",
                "KANROO_FILES_ROOT": "/absolute/path/to/allowed-files"
            }
        }
    }
}

Lass KANROO_FILES_ROOT weg, wenn der Agent keine Dateien braucht.

Dateien

Der Remote-Endpunkt schickt keine Dateiinhalte durch den Agenten. Stattdessen liefert das Tool get_file_transfer eine fertige Anfrage: Methode, Adresse, Header, Parameter und einen curl-Befehl. Der Agent führt diesen Befehl in seiner eigenen Shell aus und tauscht die Datei so direkt mit Kanroo aus. Das funktioniert für acht Vorgänge:

Operation Zweck Scope des Schlüssels
download_attachment Einen Anhang einer Aufgabe herunterladen. Lesen
download_page_attachment Eine Datei von einer Wiki-Seite herunterladen. Lesen
upload_attachment Eine Datei zu einer Aufgabe hochladen. Schreiben
upload_page_attachment Eine Datei zu einer Wiki-Seite hochladen. Schreiben
create_import Eine CSV-, Trello-JSON- oder Kanroo-JSON-Datei für einen Import hochladen. Schreiben
export_board Ein Board als JSON- oder CSV-Datei herunterladen. Lesen
export_space Einen Wiki-Space oder eine Seite als ZIP mit Markdown-Dateien herunterladen. Lesen
import_space Markdown-Dateien oder ein ZIP als Seiten in einen Wiki-Space hochladen. Schreiben

Dafür brauchst Du zwei Dinge:

  • Eine Shell. Der Agent muss Befehle ausführen können, so wie Claude Code, Codex und Cursor. Clients ohne Shell können das nicht nutzen. Nutze dort den lokalen Server oder direkt Kanroo.
  • Den Schlüssel in der Shell. Der Befehl liest den Schlüssel aus der Umgebungsvariable KANROO_API_KEY. Das Tool gibt Deinen Schlüssel nie zurück. Exportiere ihn in der Umgebung, die den Agenten startet, zum Beispiel export KANROO_API_KEY=<api-key>. Bei Codex ist das dieselbe Variable wie in seiner MCP-Konfiguration.

Der Befehl liest seine Werte aus Shell-Variablen in Großbuchstaben wie "$LOCAL_FILE" oder "$FILE_NAME". Der Agent setzt diese Variablen und führt den Befehl unverändert aus. So wird kein Wert Teil des Befehls selbst. Der Agent darf nie einen Wert aus einem Namen übernehmen, den Kanroo zurückgegeben hat, etwa aus dem Dateinamen eines Anhangs. Solche Namen stammen von anderen Mitgliedern und sind deshalb nicht vertrauenswürdig. Dasselbe gilt für alle Ausgaben der Tools, etwa Aufgabentexte, Kommentare und Wiki-Seiten.

Ein Import erzeugt nur eine Vorschau. Der Agent prüft sie und ruft dann execute_import auf. Ein Wiki-Import hat keine Vorschau: Er legt die Seiten sofort an.

Uploads haben eine Größengrenze. Bei einer selbst gehosteten Installation darf ein Anhang an einer Aufgabe oder Wiki-Seite bis zu 25 MiB groß sein, solange der Betreiber STORAGE_MAX_UPLOAD_BYTES nicht geändert hat. Bei Kanroo Cloud legt Dein Plan die Grenze fest (siehe Pläne, Preise und Limits). Eine Importdatei darf bei CSV bis zu 10 MiB und bei den anderen Quellen bis zu 25 MiB groß sein. Ein niedrigerer Wert für STORAGE_MAX_UPLOAD_BYTES senkt auch diese Grenzen.

Limits

Bei jeder Anfrage an den Remote-Endpunkt prüft Kanroo zuerst Deinen Schlüssel. Diese Prüfung wird zusätzlich zur eigentlichen Anfrage des Tools auf das Limit des Schlüssels von 2.000 Anfragen pro Minute angerechnet. Auf das Limit für Anfragen mit API-Schlüssel im Plan Deiner Organisation wird sie nicht angerechnet (siehe Pläne, Preise und Limits). Die Anfragen der Tools zählen dort mit.

Der Server wiederholt einen fehlgeschlagenen Aufruf nie von selbst. Nach einem Fehler entscheidet der Agent, was als Nächstes passiert.

Wenn etwas nicht funktioniert

  • 401: Der Schlüssel fehlt, ist falsch geschrieben, widerrufen oder abgelaufen. Prüfe, ob der Header genau Authorization: Bearer <api-key> lautet.
  • 403: Die Anfrage kam von einer Seite einer fremden Website. MCP-Clients senden solche Anfragen nicht. Prüfe, ob eine Browser-Erweiterung oder ein Proxy einen Origin-Header hinzufügt.
  • 404: Prüfe, ob die Adresse auf /mcp endet. Bei einer selbst gehosteten Installation hat der Betreiber den Remote-Endpunkt eventuell mit REMOTE_MCP_ENABLED=false abgeschaltet.
  • 429: Der Schlüssel hat sein Anfragelimit erreicht. Warte so viele Sekunden, wie Retry-After angibt, und versuche es dann erneut. Kommen von einer Adresse zu viele falsche Schlüssel, liefern weitere falsche Schlüssel ebenfalls 429. Ein korrekter Schlüssel funktioniert weiterhin. Korrigiere den Schlüssel und warte die in Retry-After genannte Zeit ab.
  • Nur manche Tools erscheinen: Der Scope des Schlüssels bestimmt die Tools. Verbinde den Agenten nach einem Schlüsselwechsel neu, damit er die Tool-Liste neu lädt. Den lokalen Server musst Du neu starten.
  • Datei-Tools erscheinen nicht: Es gibt sie nur im lokalen Server, und nur, wenn KANROO_FILES_ROOT auf einen vorhandenen Ordner zeigt, den der Server lesen und beschreiben kann. Der Remote-Endpunkt bietet stattdessen get_file_transfer.
  • Ein Datei-Tool meldet „A safe relative file path is required.“: Der Pfad ist absolut, leer oder führt mit ..-Teilen aus dem Ordner hinaus. Gib einen Pfad relativ zu KANROO_FILES_ROOT an.
  • Ein Datei-Tool meldet „The destination already exists.“: Die Zieldatei existiert bereits, und der Aufruf setzt overwrite: true nicht. Wähle einen anderen Pfad oder setze overwrite: true, um die Datei zu ersetzen.
  • Ein Datei-Tool meldet „The local path is invalid.“: Die Quelldatei fehlt oder ist keine reguläre Datei, der Zielordner fehlt, oder das Ziel ist ein Ordner. Dieselbe Antwort kommt, wenn das Ziel ein vorhandener symbolischer Link ist und overwrite: true fehlt, wenn ein symbolischer Link aus dem Ordner hinausführt oder wenn ein Ordner auf dem Pfad jemand anderem gehört oder für Gruppe oder andere beschreibbar ist. Im letzten Fall führe chmod go-w <folder> aus.
  • get_file_transfer bietet keinen Upload an: Uploads und Importe brauchen einen Schlüssel mit dem Scope „Schreiben“ oder „Admin“.
  • Der curl-Befehl liefert 401: KANROO_API_KEY fehlt in der Shell des Agenten oder ist falsch.
  • Der curl-Befehl liefert 413: Die Datei ist größer als die Upload-Grenze (siehe Dateien).
  • Der lokale Server stoppt, bevor Tools erscheinen: Prüfe die Adresse und den Schlüssel. Prüfe außerdem, ob https://<your Kanroo domain>/api/v1/users/me/context mit diesem Schlüssel im Header X-API-Key erreichbar ist. Ist KANROO_FILES_ROOT gesetzt, muss der Ordner Dir gehören und darf für Gruppe und andere nicht beschreibbar sein. Führe dazu chmod go-w <folder> aus.
  • Ein Client meldet ungültige Protokollausgabe vom lokalen Server: Starte ihn nicht über einen Wrapper, der etwas auf die Standardausgabe schreibt.

War diese Seite hilfreich?