Skip to main content

BookStack MCP Server – Installationsanleitung

Kontext

Diese Anleitung dokumentiert die Einrichtung des bookstack-mcp-server (npm-Paket von pnocera), der Claude über das Model Context Protocol direkten Zugriff auf diese BookStack-Instanz gibt.

Voraussetzungen

  • Laufende BookStack-Instanz mit Zugriff auf einen Benutzer-Account
  • Die Rolle des Accounts benötigt die Berechtigung "Access system API" (BookStack: Settings → Roles → <Rolle> → Bereich "System")
  • Bun-Runtime ≥ 1.1.0 installiert und im PATH
    • Das npm-Paket liefert kein kompiliertes JavaScript aus, sondern startet die TypeScript-Quelle direkt über das Shebang #!/usr/bin/env bun. Node/npx allein reicht nicht aus – Bun muss auf der Maschine vorhanden sein.
    • Prüfen: bun --version
    • Installation z. B. via winget: winget install Oven-sh.Bun
  • Claude Code CLI installiert

Schritt 1: API-Token in BookStack erzeugen

  1. In BookStack einloggen.
  2. Oben rechts auf das Profil-Icon klicken → Edit Profile.
  3. Tab API Tokens öffnen → Create Token.
  4. Namen vergeben, Token erzeugen.
  5. Token-ID und Token-Secret notieren (Secret wird nur einmal angezeigt).
  6. Für die Konfiguration werden beide Teile mit Doppelpunkt kombiniert: token_id:token_secret.

Schritt 2: MCP-Server zu Claude Code hinzufügen

claude mcp add bookstack --scope user \
  --env BOOKSTACK_BASE_URL=https://<deine-bookstack-domain>/api \
  --env BOOKSTACK_API_TOKEN=<token_id>:<token_secret> \
  --env MCP_TRANSPORT=stdio \
  -- npx -y bookstack-mcp-server

Wichtige Punkte:

  • BOOKSTACK_BASE_URL muss zwingend auf /api enden – nicht nur die reine Domain angeben.
  • MCP_TRANSPORT=stdio ist notwendig. Ohne diese Variable startet der Server im HTTP-Modus, verlangt zusätzlich einen MCP_AUTH_TOKEN (separates Bearer-Secret für eingehende Verbindungen, z. B. via openssl rand -hex 32) und einen freien Port (Default 3000).
  • --scope user legt den Server user-weit an, nicht nur projektbezogen.

Schritt 3: Verbindung prüfen

  • In Claude Code /mcp ausführen → Server bookstack sollte als verbunden angezeigt werden.
  • Testaufruf, z. B. bookstack_search oder bookstack_books_list → sollte JSON-Daten liefern, kein HTML.

Claude Desktop (statt/zusätzlich zu Claude Code)

Grundsätzlich derselbe JSON-Block unter mcpServers, aber ein paar Desktop-spezifische Fallstricke:

  • Config-Pfad bei paketierter Installation (App-Installer/MSIX-Variante): nicht der klassische Pfad %APPDATA%\Claude\claude_desktop_config.json, sondern %LOCALAPPDATA%\Packages\Claude_pzs8sxrjxfjjc\LocalCache\Roaming\Claude\claude_desktop_config.json. Am zuverlässigsten über die App selbst finden: Settings → Developer → "Edit Config".
  • MCP_TRANSPORT: "stdio" nicht vergessen – ohne diese Env-Variable startet bookstack-mcp-server im HTTP-Modus (Port 3000, zusätzlich MCP_AUTH_TOKEN nötig) und bricht beim Start sofort ab, weil dieser Token fehlt. Claude Desktop meldet dann nur "kann nicht verbinden", ohne den eigentlichen Grund zu nennen.
  • Die App läuft nach dem Schließen des Fensters im Hintergrund weiter (Tray-Icon) und schreibt die Config-Datei bei jedem Öffnen/Schließen neu (v. a. den preferences-Block). Der mcpServers-Block wurde dabei im Test nicht überschrieben – trotzdem zur Sicherheit: Datei nur bearbeiten, wenn die App über Tray-Icon → Beenden vollständig beendet wurde, danach neu starten. Nur ein Fenster zu schließen reicht nicht.
  • Minimales mcpServers-Beispiel für Claude Desktop: 
    {
  "mcpServers": {
    "bookstack": {
      "command": "npx",
      "args": ["-y", "bookstack-mcp-server"],
      "env": {
        "BOOKSTACK_BASE_URL": "https://<domain>/api",
        "BOOKSTACK_API_TOKEN": "<token_id>:<token_secret>",
        "MCP_TRANSPORT": "stdio"
      }
    }
  }
}
  • Verifikation: im Chat-Eingabefeld erscheint ein Stecker-/Werkzeug-Icon, darunter sollte bookstack als verbunden aufgeführt sein.

Troubleshooting

Symptom Ursache Fix
Tool liefert rohes HTML (Login-Seite) statt JSON BOOKSTACK_BASE_URL ohne /api-Suffix → Anfrage landet auf normaler Web-Route statt REST-API URL um /api ergänzen
MCP error -32600: Requested resource not found bei bookstack_system_info Einzelnes Tool/Endpoint-Problem, nicht grundsätzlich Mit anderem Tool (z. B. bookstack_search) erneut testen
401 / Auth-Fehler BOOKSTACK_API_TOKEN nicht im Format token_id:token_secret Token in BookStack neu erzeugen, beide Teile mit : kombinieren
Änderung an ~/.claude.json wirkt nicht Laufender stdio-Prozess wurde mit alten Env-Variablen gestartet Claude-Code-Session neu starten
Server startet gar nicht (nur im HTTP-Modus relevant) BOOKSTACK_API_TOKEN fehlt komplett Env-Variable setzen, Prozess neu starten

Sicherheitshinweise

  • Der BookStack-API-Token gewährt API-Zugriff im vollen Umfang der Rolle des Accounts, für den er erzeugt wurde (ggf. inkl. Create/Update/Delete auf Books/Pages/Users) – als Secret behandeln, nicht in Klartext-Notizen, Tickets oder Chats teilen.
  • ~/.claude.json liegt lokal und unverschlüsselt auf der Maschine; Zugriff entsprechend einschränken.
  • Falls statt Stdio der HTTP-Transport genutzt wird: zusätzlich MCP_AUTH_TOKEN generieren (z. B. openssl rand -hex 32). Dieser ist nicht identisch mit dem BookStack-Token und schützt den eingehenden /message-Endpoint.

Alternative: offizielle Bun-Variante

Das Paket-README empfiehlt eigentlich bunx statt npx:

claude mcp add bookstack --scope user \
  --env BOOKSTACK_BASE_URL=https://<domain>/api \
  --env BOOKSTACK_API_TOKEN=<token_id>:<token_secret> \
  --env MCP_TRANSPORT=stdio \
  -- bunx bookstack-mcp-server

In der bestehenden Konfiguration funktioniert auch npx -y bookstack-mcp-server, weil npm auf Windows das Shebang (#!/usr/bin/env bun) im generierten Wrapper-Skript berücksichtigt und automatisch bun aufruft, sofern es im PATH gefunden wird.

Andere MCP-Server-Implementierungen für BookStack (falls Alternative gewünscht)

  • pnocera/bookstack-mcp-server (aktuell genutzt; npm: bookstack-mcp-server; 59 Tools; benötigt Bun) — https://github.com/pnocera/bookstack-mcp-server
  • h4sht/bookstack-mcp (25 Tools; reines Node.js, kein Bun nötig; Installation: claude mcp add bookstack -- npx github:h4sht/bookstack-mcp) — https://github.com/h4sht/bookstack-mcp
  • oculairmedia/Bookstack-MCP (Python/FastMCP, Fokus u. a. auf Bild-Galerie-Workflows)
  • weitere Optionen: yellowgg2/mcp-bookstack, pacyworld/bookstack-mcp (Multi-Instanz), Derron-Knox/bookstack-mcp-server

Quellen

Erstellt von Claude Sonnet 5 (claude-sonnet-5) via API, ausgehend von der Obsidian-Notiz Themes/BookStack MCP/2026-09-17 BookStack MCP Installationsanleitung.md.

No Comments
Back to top