Claude Mermaid MCP-Server

MCP-Server zum Rendern von Mermaid-Diagrammen in Claude Code mit Live-Reload-Funktionalität und einer integrierten Fähigkeit für Expertenanleitungen.

Diagramme werden automatisch in Ihrem Browser gerendert und in Echtzeit aktualisiert, während Sie sie verfeinern. Perfekt für iterative Diagrammentwicklung und Dokumentations-Workflows.

✨ Funktionen

• 🔄 Live-Reload - Diagramme werden beim Bearbeiten automatisch im Browser aktualisiert

• 🎨 Mehrere Speicherformate - Export als SVG, PNG oder PDF

• 🌈 Themes - Wählen Sie zwischen Standard-, Forest-, Dark- oder Neutral-Themes

• 📐 Anpassbar - Steuern Sie Abmessungen, Skalierung und Hintergrundfarben

• 🪄 Interaktive Vorschau - Diagramme durch Ziehen verschieben, mit Browser-Steuerelementen zoomen, Position mit einem Klick zurücksetzen

• ⬇️ Browser-Export - Laden Sie Diagramme direkt aus der Vorschau als SVG oder PNG herunter

• 🗂️ Mehrere Vorschauen - Verwenden Sie preview_id, um gleichzeitig an mehreren Diagrammen zu arbeiten

• 💾 Persistente Arbeitsdateien - Live-Vorschauen werden unter ~/.config/claude-mermaid/live gespeichert

• 🤖 Integrierte Fähigkeit - Enthält eine Claude-Fähigkeit mit Best Practices und Expertenanleitungen zum Erstellen von Diagrammen

Related MCP server: mcp-mermaid-validator

Architektur

🚀 Schnellstart

1. Installation

Plugin-Installation (Empfohlen)

Fügen Sie in Claude Code den Marketplace hinzu und installieren Sie das Plugin:

/plugin marketplace add veelenga/claude-mermaid
/plugin install claude-mermaid@claude-mermaid

Starten Sie anschließend Claude Code neu, um das Plugin zu aktivieren.

Über npm:

npm install -g claude-mermaid

Aus dem Quellcode:

git clone https://github.com/veelenga/claude-mermaid.git
cd claude-mermaid
npm install && npm run build && npm install -g .

2. Installation überprüfen

Plugin-Installation: Der MCP-Server wird automatisch konfiguriert. Überprüfen Sie dies einfach:

/mcp

Sie sollten mermaid in der Liste der MCP-Server sehen.

npm-Installation: Konfigurieren Sie den MCP-Server manuell:

claude mcp add --scope user mermaid claude-mermaid

Überprüfen Sie dann:

claude mcp list

Sie sollten mermaid: claude-mermaid - ✓ Connected sehen.

🔌 Andere MCP-Client-Konfigurationen

Obwohl dieser Server für Claude Code optimiert ist, funktioniert er mit jedem MCP-kompatiblen Client. Hier erfahren Sie, wie Sie ihn für andere beliebte Tools konfigurieren:

Fügen Sie dies zu Ihrer Codex-MCP-Einstellungsdatei hinzu (~/.codex/mcp_settings.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Oder konfigurieren Sie es über die Codex-CLI:

codex mcp add mermaid claude-mermaid

Fügen Sie dies zu Ihrer Cursor-MCP-Konfigurationsdatei hinzu (.cursor/mcp.json oder Einstellungen):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Oder verwenden Sie die Einstellungs-UI von Cursor:

1. Öffnen Sie die Cursor-Einstellungen (Cmd/Ctrl + ,)

2. Navigieren Sie zu MCP-Servern

3. Fügen Sie einen neuen Server mit dem Befehl claude-mermaid hinzu

Wenn Sie die Cline-Erweiterung für VSCode verwenden:

1. Öffnen Sie die VSCode-Einstellungen (Cmd/Ctrl + ,)

2. Suchen Sie nach "Cline MCP"

3. Fügen Sie dies zum MCP-Einstellungs-JSON hinzu:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Fügen Sie dies zur MCP-Konfigurationsdatei von Windsurf hinzu:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Der Speicherort der Konfiguration variiert je nach Plattform:

• macOS: ~/Library/Application Support/Windsurf/mcp.json

• Linux: ~/.config/windsurf/mcp.json

• Windows: %APPDATA%\Windsurf\mcp.json

Fügen Sie dies zur MCP-Konfigurationsdatei der Gemini CLI hinzu (~/.gemini/mcp.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Oder verwenden Sie die Gemini CLI zur Konfiguration:

gemini config mcp add mermaid --command claude-mermaid

Verwenden Sie für jeden MCP-kompatiblen Client die Standardkonfiguration:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Der Befehl claude-mermaid sollte nach der Installation in Ihrem PATH verfügbar sein.

Hinweis: Einige Clients erfordern möglicherweise den vollständigen Pfad zur ausführbaren Datei:

• Pfad finden: which claude-mermaid (Unix/macOS) oder where claude-mermaid (Windows)

• Verwenden Sie den absoluten Pfad in der Konfiguration: "command": "/path/to/claude-mermaid"

💡 Verwendung

Bitten Sie Claude Code einfach, Mermaid-Diagramme auf natürliche Weise zu erstellen. Wenn es als Plugin installiert ist, bietet die integrierte mermaid-diagrams-Fähigkeit Expertenanleitungen, Best Practices und automatisches Workflow-Management.

Grundlegende Beispiele

"Create a Mermaid diagram showing the user authentication flow"
"Draw a sequence diagram for the payment process"
"Generate a flowchart for the deployment pipeline"

Fortgeschrittene Beispiele

Mit benutzerdefinierter Formatierung:

"Create a dark theme architecture diagram with transparent background"
"Generate a forest theme flowchart and save to ./docs/flow.svg"

Mit spezifischem Ausgabeformat:

"Create an ER diagram and save as PDF to ./docs/schema.pdf"
"Save the flowchart as PNG to ./docs/flow.png"

Hinweis: Der Browser zeigt für die Live-Vorschau immer SVG an, während beim Speichern das von Ihnen gewählte Format verwendet wird.

Iterative Verfeinerung:

"Create a class diagram for the User module"
// Browser opens with live preview
"Add the Address and Order classes with relationships"
// Diagram updates automatically in browser!

Vollständiges Beispiel

"Create a flowchart and save to ./docs/auth-flow.svg:

graph LR
    A[User Login] --> B{Valid Credentials?}
    B -->|Yes| C[Access Granted]
    B -->|No| D[Access Denied]
    C --> E[Dashboard]
    D --> F[Try Again]

    style A fill:#e1f5ff
    style C fill:#d4edda
    style D fill:#f8d7da
"

Das Diagramm wird unter ./docs/auth-flow.svg gespeichert und mit aktiviertem Live-Reload in Ihrem Browser geöffnet.

🔧 Tools und Parameter

Der MCP-Server stellt zwei Tools bereit:

1. mermaid_preview — Rendern und Öffnen einer Live-Vorschau

• diagram (String, erforderlich) — Mermaid-Diagrammcode

• preview_id (String, erforderlich) — Kennung für diese Vorschau-Sitzung. Verwenden Sie unterschiedliche IDs für mehrere gleichzeitige Diagramme (z. B. architecture, flow).

• format (String, Standard svg) — Eines von svg, png, pdf. Die Live-Vorschau ist nur für svg verfügbar.

• theme (String, Standard default) — Eines von default, forest, dark, neutral.

• background (String, Standard white) — Hintergrundfarbe. Beispiele: transparent, white, #F0F0F0.

• width (Zahl, Standard 800) — Diagrammbreite in Pixeln.

• height (Zahl, Standard 600) — Diagrammhöhe in Pixeln.

• scale (Zahl, Standard 2) — Skalierungsfaktor für eine höhere Ausgabequalität.

2. mermaid_save — Speichern des aktuellen Live-Diagramms unter einem Pfad

• save_path (String, erforderlich) — Zielpfad (z. B. ./docs/diagram.svg).

• preview_id (String, erforderlich) — Muss mit der in mermaid_preview verwendeten preview_id übereinstimmen.

• format (String, Standard svg) — Eines von svg, png, pdf. Wenn die Live-Arbeitsdatei für dieses Format noch nicht existiert, wird sie vor dem Speichern bei Bedarf gerendert.

🎯 Funktionsweise des Live-Reloads

1. Erstes Rendern: Öffnet das Diagramm im Browser unter http://localhost:3737/{preview_id}

2. Änderungen vornehmen: Bearbeiten Sie das Diagramm über Claude Code

3. Automatische Aktualisierung: Der Browser erkennt Änderungen über WebSocket und lädt neu

4. Statusanzeige: Grüner Punkt = verbunden, Roter Punkt = verbindet neu

Der Live-Server verwendet die Ports 3737-3747 und findet automatisch einen verfügbaren Port.

Steuerelemente der Live-Vorschau

• Verschieben: Klicken und ziehen Sie das Diagramm, um es zu bewegen

• Zoomen: Verwenden Sie den Browser-Zoom (Strg/Cmd + +/- oder Pinch-to-Zoom auf dem Trackpad)

• Position zurücksetzen: Klicken Sie auf die ⊙-Schaltfläche in der Statusleiste, um das Diagramm neu zu zentrieren

• Exportieren: Klicken Sie auf die ⬇-Schaltfläche, um es als SVG oder PNG herunterzuladen

Hinweise

• Die Live-Vorschau ist nur für das svg-Format verfügbar; PNG/PDF werden ohne Live-Reload gerendert.

• Für Sequenzdiagramme unterstützt Mermaid keine style-Direktiven innerhalb von sequenceDiagram.

🖥️ Eigenständiger Server

Sie können den Vorschau-Server ohne einen KI-Agenten mit dem --serve-Flag starten:

claude-mermaid --serve

Dies öffnet die Diagrammgalerie in Ihrem Browser mit allen zuvor gerenderten Diagrammen. Nützlich zum Durchsuchen und Exportieren von Diagrammen außerhalb einer Claude Code-Sitzung.

🛠️ Entwicklung

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev

# Start the MCP server directly
npm start

📝 Fehlerbehebung

Fehler: Cannot find package 'puppeteer':

Dies ist ein seltenes, umgebungsspezifisches Problem. Versuchen Sie diese Lösungen:

1. claude-mermaid global installieren:

   npm install -g claude-mermaid

2. Das Plugin in Claude Code neu installieren:

   /plugin uninstall claude-mermaid
   /plugin install claude-mermaid@claude-mermaid

Server verbindet nicht:

# Check if server is installed
claude-mermaid -v

# Reinstall if needed
npm install -g claude-mermaid

# Verify MCP configuration
claude mcp list

Fehler "Permission denied":

# Make sure the binary is executable
chmod +x $(which claude-mermaid)

Port wird bereits verwendet:

• Der Server verwendet die Ports 3737-3747

• Er findet automatisch einen verfügbaren Port

• Überprüfen Sie, ob ein anderer Prozess diese Ports verwendet: lsof -i :3737-3747

Diagramme werden nicht gerendert oder Live-Reload funktioniert nicht:

Der Server protokolliert in ~/.config/claude-mermaid/logs/:

• mcp.log - Tool-Anfragen und Diagramm-Rendering

• web.log - HTTP/WebSocket-Verbindungen und Live-Reload

Aktivieren Sie das Debug-Logging in Ihrer MCP-Konfiguration:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid",
      "env": {
        "CLAUDE_MERMAID_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Überprüfen Sie dann die Protokolle:

# View MCP operations
tail -f ~/.config/claude-mermaid/logs/mcp.log

# View WebSocket connections
tail -f ~/.config/claude-mermaid/logs/web.log

Verfügbare Log-Level: DEBUG, INFO (Standard), WARN, ERROR, OFF

🤝 Mitwirken

Beiträge sind willkommen! Bitte fühlen Sie sich frei, einen Pull Request einzureichen.

📄 Lizenz

MIT - siehe LICENSE-Datei für Details

🔗 Links

• GitHub-Repository

• npm-Paket

• Claude Code-Dokumentation

• Mermaid-Dokumentation

👀 Siehe auch

Wenn Ihnen dieses Projekt gefällt, könnten Sie sich auch für Folgendes interessieren:

• preview-skills — Vorschau-Fähigkeiten zur Visualisierung von Dateien im Browser (Markdown, CSV, JSON, Mermaid und mehr)

Gehostete Bereitstellung

Eine gehostete Bereitstellung ist auf Fronteir AI verfügbar.