planka-mcp

Steuern Sie ein Planka-2.x-Board über 15 MCP-Tools von Claude Code aus. Schreibvorgänge werden erneut gelesen und verifiziert, sodass ein gemeldeter Erfolg dem Board entspricht. Ein optionaler Workflow macht dieses Board zu einem dauerhaften Speicher für Agentenarbeit.

Leer en español

You talk to Claude Code
          │
          ▼
  planka-mcp (stdio) ─── HTTPS + JSON ───▶ Planka 2.x
          │                                  │
          └──── reads the result back ◀──────┘

[!WARNUNG] Das alte Paket @gogogadgetbytes/planka-mcp kann Erfolg melden, während es auf Planka 2.x nichts tut. Lesen Sie die vier Fallstricke bei stillem Fehlschlagen, bevor Sie eine bestehende Installation ersetzen.

Neu bei MCP? Lesen Sie dies zuerst

MCP ist ein Standard, der es Claude Code ermöglicht, Tools aufzurufen, die von einem anderen Programm bereitgestellt werden. Dieses Repository führt ein kleines lokales Programm aus, das diese Tool-Aufrufe in Planka-API-Anfragen übersetzt. Es benötigt Planka-Anmeldedaten, da es als dedizierter Planka-Benutzer agiert, nicht als Claude selbst. Die Anmeldedaten bleiben auf Ihrem Rechner und werden nie in die .mcp.json-Datei auf Projektebene geschrieben. Claude Code lädt MCP-Server beim Start einer Sitzung. Starten Sie es daher nach der Einrichtung oder Konfigurationsänderungen neu.

Related MCP server: Planka MCP Server

Voraussetzungen

• Node.js 18 oder neuer und npm

• Eine erreichbare Planka-2.x-Instanz

• Ein dedizierter Planka-Benutzer, der das Zielprojekt und das Board sehen kann

• Claude Code installiert und als claude verfügbar

• Eine Projektmanager-Rolle nur, wenn die Einrichtung ein Board erstellen muss

Linux und macOS werden unterstützt. Keine Bun-Laufzeit erforderlich.

Installation in 5 Minuten

Klonen Sie das Repository und führen Sie den geführten Installer aus:

git clone https://github.com/omnicoreos/planka-mcp.git
cd planka-mcp
./scripts/setup.sh

Die Einrichtung fragt nach der Planka-URL, der Agenten-E-Mail oder dem Benutzernamen und dem Passwort. Sie validiert diese Anmeldedaten, bevor sie die Konfiguration schreibt, ermöglicht die Auswahl oder Erstellung eines Boards und führt dann einen echten Smoke-Test für Erstellen/Label/Kommentieren/Löschen durch.

Sie bietet zwei Claude-Code-Konfigurationen an:

In beiden Fällen speichert die Einrichtung die Anmeldedaten außerhalb von Git in ~/.config/planka-mcp/config.json mit Modus 0600 und erstellt den privaten Launcher ~/.local/bin/planka-mcp. Eine generierte Team-Konfiguration enthält kein Passwort:

{
  "mcpServers": {
    "planka": {
      "type": "stdio",
      "command": "${HOME}/.local/bin/planka-mcp",
      "args": []
    }
  }
}

Der Installer kann bedenkenlos erneut ausgeführt werden. Er aktualisiert den planka-Eintrag, verwendet vorhandene Workflow-Listen und -Labels erneut und löscht seine temporäre Smoke-Test-Karte.

Verifizieren, dass es funktioniert

Prüfen Sie zuerst die Konfiguration von Claude Code:

claude mcp list
claude mcp get planka

Starten Sie dann Claude Code vollständig neu. Wenn Sie .mcp.json gewählt haben, öffnen Sie Claude Code in diesem Projekt und genehmigen Sie den projektspezifischen Server, wenn Sie dazu aufgefordert werden.

Fragen Sie Claude Code:

Show me my Planka projects and boards. In the Pending list, create a card named
"MCP is working" with the description "Created from Claude Code", then read it back.

Wenn Claude die Tools nicht sehen kann, starten Sie zuerst neu und folgen Sie dann der Fehlerbehebung.

Die 15 Tools

IDs sind Strings. Beginnen Sie mit planka_get_structure und verwenden Sie dann die von Planka zurückgegebenen IDs; raten Sie nicht.

Jedes Eingabefeld und eine vollständige Payload für jedes Tool finden Sie in der Tool-Referenz.

Optionaler Agenten-Workflow

Der MCP-Server funktioniert eigenständig. Die optionale Methode löst ein anderes Problem: zu bewahren, warum Arbeit existiert, was sich geändert hat und was zwischen Agentenitzungen weiterhin gilt.

Übernehmen Sie sie in Ebenen:

1. Verwenden Sie nur die MCP-Tools.

2. Fügen Sie die Board-Zustände, die Kartenvorlage und die menschlichen Handshakes hinzu.

3. Fügen Sie einen Worktree pro Karte hinzu, mit einem Direktor, der die Worker koordiniert.

Beginnen Sie mit Ein Board, das die Sitzung überlebt. Die Board-Vorlage, die kopierbaren Claude-Code-Skills und der optionale Worktree-Helfer sind unabhängige Teile.

Fehlerbehebung

• Symptome, Ursachen und genaue Lösungen

• Warum Planka 2.x ältere MCP-Server still bricht

• Vollständige Tool-Payloads

Wenn Sie einen Fehler melden, geben Sie die Planka-Version, die Node-Version, den Tool-Namen und den Fehlertext an. Fügen Sie niemals Anmeldedaten oder Zugriffstokens ein.

Credits und Lizenz

Dies ist ein MIT-lizenzierter Fork von gogogadgetbytes/planka-mcp, keine Neuimplementierung von Grund auf. Siehe CREDITS.md für die Upstream-Zuschreibung, gepflegte Fixes und unbeantwortete Pull Requests.

Siehe LICENSE für die ursprünglichen und aktuellen Hinweise zu Mitwirkenden.

Entwicklung

npm ci
npm run build
npm test

Der echte Smoke-Test ist opt-in, da er ein beschreibbares Board verändert und sich danach selbst aufräumt:

export PLANKA_BASE_URL="https://planka.example.com"
export PLANKA_AGENT_EMAIL="agent@example.com"
export PLANKA_AGENT_PASSWORD="<YOUR_PASSWORD>"
export PLANKA_SMOKE_BOARD_ID="1234567890123456789"
npm run test:smoke

Siehe CONTRIBUTING.md, bevor Sie eine Änderung öffnen. Die Release-Identität ist in project.identity.json zentralisiert; aktualisieren Sie sie und führen Sie npm run sync:identity aus, bevor Sie unter Ihrem eigenen Namespace veröffentlichen.