Skip to main content
Glama
Mermaid MCP Server

Mermaid MCP Server

by wwwzhouhui

Mermaid MCP Server

Mermaid-Diagramm-Konvertierungsserver auf Basis des Model Context Protocol (MCP), der KI-Clients leistungsstarke Diagrammgenerierungsfunktionen bietet

License Python MCP UV


Projektbeschreibung

Mermaid MCP Server ist ein professioneller Mermaid-Diagramm-Konvertierungsserver auf Basis des Model Context Protocol (MCP), der KI-Clients leistungsstarke Diagrammgenerierungsfunktionen bietet. Dieses Projekt kann Mermaid-Diagrammcode in Bilddateien in mehreren Formaten (PNG, JPG, SVG, PDF) konvertieren, sodass Benutzer in verschiedenen KI-Clients, die das MCP-Protokoll unterstützen, problemlos hochwertige Diagramme erstellen können.

Kernfunktionen

  • Mehrformat-Ausgabe: Unterstützt mehrere Bildformate wie PNG, JPG, SVG, PDF

  • Theme-Anpassung: Integriert vier elegante Themes: default, dark, neutral, forest

  • Benutzerdefinierte Optionen: Unterstützt Anpassung von Hintergrundfarbe, Bildgröße und anderen Parametern

  • Syntaxvalidierung: Bietet Echtzeit-Validierung der Mermaid-Syntax

  • Beispielressourcen: Integriert umfangreiche Beispielcodes für verschiedene Diagrammtypen

  • Fehlerbehandlung: Vollständiger Fehlerbehandlungsmechanismus mit benutzerfreundlichen Fehlermeldungen

  • STDIO/SSE-Dualmodus: Unterstützt sowohl STDIO- als auch SSE-Kommunikationsmodi

  • uv-Paketverwaltung: Verwendet den ultraschnellen uv-Paketmanager


Related MCP server: mcp-mermaid-validator

Funktionsübersicht

Funktionsname

Funktionsbeschreibung

Technologie-Stack

Status

Diagrammkonvertierung

Mermaid-Code in Bild umwandeln

mermaid.ink API

✅ Stabil

Mehrformat-Ausgabe

PNG/JPG/SVG/PDF

requests + base64

✅ Stabil

Theme-Anpassung

4 integrierte Themes

mermaid.ink

✅ Stabil

Syntaxvalidierung

Echtzeit-Syntaxprüfung

mermaid-cli

✅ Stabil

Beispielressourcen

Umfangreiche Diagrammbeispiele

Statische Ressourcen

✅ Stabil

Fehlerbehandlung

Vollständige Fehlermeldungen

Python-Ausnahmebehandlung

✅ Stabil

MCP-Protokoll

Model Context Protocol

mcp[cli]

✅ Stabil

SSE-Modus

Server-Sent Events

FastAPI + Uvicorn

✅ Stabil


Technische Architektur

Technologie

Version

Verwendungszweck

Python

3.12+

Hauptentwicklungssprache

MCP

1.9+

Model Context Protocol

FastAPI

0.104+

Web-Framework (SSE-Modus)

Uvicorn

0.24+

ASGI-Server

requests

2.31+

HTTP-Client

uv

latest

Python-Paketmanager

Kommunikationsarchitektur

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            通信架构图                                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   ┌──────────────────┐       ┌─────────────────────────┐       ┌─────────────┐ │
│   │  AI 客户端         │ ◄────► │   Mermaid MCP Server    │ ◄────► │ Mermaid API │ │
│   │ (Cursor/Claude)   │       │   STDIO/SSE             │       │  mermaid.ink│ │
│   └──────────────────┘       └─────────────────────────┘       └─────────────┘ │
│           │                            │                              │        │
│           ▼                            ▼                              ▼        │
│   AI 对话界面                MCP 协议通信              图表渲染转换      │
│   生成图表请求                双向数据传输              返回图像数据     │
│                                                                                 │
└─────────────────────────────────────────────────────────────────────────────────┘

Installationsanleitung

Systemanforderungen

  • Python 3.12+

  • uv-Paketmanager (empfohlen)

Abhängigkeiten installieren

Methode 1: Installation mit uv (empfohlen)

# 克隆仓库
git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server

# 安装依赖
uv sync

Methode 2: Installation mit pip

pip install -r requirements.txt

Verwendungsanleitung

Client-Konfiguration

Cursor-Konfiguration

Fügen Sie in der Datei ~/.cursor/mcp.json die folgende Konfiguration hinzu:

STDIO-Modus (empfohlen):

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "command": "uvx",
      "args": [
        "mermaid-mcp-server-png-pdf-jpg-svg"
      ]
    }
  }
}

SSE-Modus:

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "url": "http://127.0.0.1:8003/sse"
    }
  }
}

Cherry Studio-Konfiguration

  1. Öffnen Sie Cherry Studio

  2. Gehen Sie zu Einstellungen → MCP-Server → Server hinzufügen

  3. Konfigurieren Sie die Parameter:

    • Name: mermaid-mcp-server-png-pdf-jpg-svg

    • Beschreibung: Mermaid-Diagrammgenerierungsdienst

    • Typ: STDIO

    • Befehl: uvx

    • Parameter: mermaid-mcp-server-png-pdf-jpg-svg

  4. Klicken Sie auf Speichern und aktivieren

Cherry Studio-Konfigurationsbeispiel

Claude Desktop-Konfiguration

Fügen Sie in der Datei claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "command": "uvx",
      "args": [
        "mermaid-mcp-server-png-pdf-jpg-svg"
      ]
    }
  }
}

Continue.dev-Konfiguration

Fügen Sie in der Datei config.json hinzu:

{
  "mcpServers": {
    "mermaid-mcp-server-png-pdf-jpg-svg": {
      "command": "uvx",
      "args": [
        "mermaid-mcp-server-png-pdf-jpg-svg"
      ]
    }
  }
}

Dienst starten

STDIO-Modus (empfohlen für Desktop-Clients)

uv run python main.py

SSE-Modus (für Netzwerkverbindungen)

uv run python main.py --sse

Konfigurationshinweise

Umgebungsvariablen-Konfiguration

Variablenname

Beschreibung

Standardwert

HOST

Serveradresse

0.0.0.0

PORT

Serverport

8003

LOG_LEVEL

Protokollebene

INFO

MERMAID_API_BASE_URL

Mermaid-API-Adresse

https://mermaid.ink

REQUEST_TIMEOUT

Anforderungs-Timeout (Sekunden)

30

DEBUG

Debug-Modus

false

DEVELOPMENT_MODE

Entwicklungsmodus

false


Verfügbare Tools

1. convert_mermaid_to_image

Konvertiert Mermaid-Diagrammcode in Bilddateien in mehreren Formaten

Parameter:

  • mermaid_code (string): Mermaid-Diagrammcode

  • output_format (string, optional): Ausgabeformat, unterstützt png, jpg, svg, pdf, Standard "png"

  • theme (string, optional): Theme-Stil, unterstützt default, dark, neutral, forest, Standard "default"

  • background_color (string, optional): Hintergrundfarbe, Hexadezimalcode

  • width (number, optional): Bildbreite (Pixel)

  • height (number, optional): Bildhöhe (Pixel)

Unterstützte Ausgabeformate: PNG, JPG, SVG, PDF

2. validate_mermaid_syntax

Überprüft die syntaktische Korrektheit von Mermaid-Diagrammcode

Parameter:

  • mermaid_code (string): Zu validierender Mermaid-Diagrammcode

Rückgabewerte:

  • valid (boolean): Ob die Validierung bestanden wurde

  • error_message (string): Fehlermeldung (falls Validierung fehlgeschlagen)

3. get_supported_options

Ruft die vom Konverter unterstützten Optionen ab

Rückgabewerte:

  • themes (array): Liste der unterstützten Themes

  • formats (array): Liste der unterstützten Formate


Unterstützte Diagrammtypen

  • Flussdiagramm (Flowchart): Zur Darstellung von Abläufen und Algorithmen

  • Sequenzdiagramm (Sequence Diagram): Zur Darstellung von Interaktionen zwischen Objekten

  • Gantt-Diagramm (Gantt Chart): Für Projektfortschrittsverwaltung

  • Kreisdiagramm (Pie Chart): Zur Darstellung von Datenanteilen

  • Git-Diagramm (Git Graph): Zur Darstellung der Git-Commit-Historie

  • Mindmap (Mind Map): Zur Darstellung von Wissensstrukturen

  • Klassendiagramm (Class Diagram): Zur Darstellung von Klassenstrukturen


Verwendungsbeispiele

Flussdiagramm-Beispiel

请使用 convert_mermaid_to_image 工具生成一个流程图:
flowchart TD
    A[开始] --> B{判断条件}
    B -->|是 | C[执行动作 1]
    B -->|否 | D[执行动作 2]
    C --> E[结束]
    D --> E

Sequenzdiagramm-Beispiel

请使用 convert_mermaid_to_image 工具生成一个时序图,使用深色主题:
sequenceDiagram
    participant 用户
    participant 系统
    participant 数据库

    用户->>系统:登录请求
    系统->>数据库:验证用户
    数据库-->>系统:返回结果
    系统-->>用户:登录成功

Syntaxvalidierungs-Beispiel

首先使用 validate_mermaid_syntax 验证语法,然后使用 convert_mermaid_to_image 生成图表

Ressourcenbeispiele

Diagrammbeispiele abrufen

Über die folgenden Ressourcen-URIs können Sie Beispiele für verschiedene Diagrammtypen abrufen:

  • mermaid://examples/flowchart - Flussdiagramm-Beispiel

  • mermaid://examples/sequence - Sequenzdiagramm-Beispiel

  • mermaid://examples/gantt - Gantt-Diagramm-Beispiel

  • mermaid://examples/pie - Kreisdiagramm-Beispiel

  • mermaid://examples/gitgraph - Git-Diagramm-Beispiel

  • mermaid://examples/mindmap - Mindmap-Beispiel

  • mermaid://examples/class - Klassendiagramm-Beispiel


Projektstruktur

mermaid_mcp_server/
├── mermaid_mcp_server/       # 核心模块
│   ├── __init__.py
│   └── main.py             # 主程序入口
├── requirements.txt          # 依赖列表(pip)
├── pyproject.toml           # 项目配置(uv)
├── .env.example            # 环境变量示例
├── README.md               # 项目文档
└── .vscode/                # VSCode 配置
    └── settings.json

Entwicklungsleitfaden

Lokale Entwicklung

# 克隆仓库
git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server

# 安装依赖
uv sync

# 配置环境变量
cp .env.example .env

# 启动服务(STDIO 模式)
uv run python main.py

# 启动服务(SSE 模式)
uv run python main.py --sse

Debug-Modus

Detaillierte Protokollausgabe aktivieren:

export LOG_LEVEL=DEBUG
uv run python main.py

Häufig gestellte Fragen

A:

  1. Überprüfen Sie die Netzwerkverbindung und Firewall-Einstellungen

  2. Stellen Sie sicher, dass die mermaid.ink-API erreichbar ist

  3. Überprüfen Sie die Proxy-Einstellungen

A:

  1. Verwenden Sie das Tool validate_mermaid_syntax zur Syntaxprüfung

  2. Konsultieren Sie die offizielle Mermaid-Dokumentation

  3. Verwenden Sie den Code aus den Beispielressourcen

A:

  1. Vereinfachen Sie den Diagramminhalt

  2. Teilen Sie es in mehrere kleinere Diagramme auf

  3. Passen Sie die Bildgrößenparameter an

A:

  1. Installieren Sie den uv-Paketmanager: curl -LsSf https://astral.sh/uv/install.sh | sh

  2. Oder installieren Sie das Paket global mit pip

  3. Überprüfen Sie die PATH-Umgebungsvariable

A:

  1. Stellen Sie sicher, dass der Dienst im SSE-Modus gestartet wurde

  2. Überprüfen Sie, ob Port 8003 belegt ist

  3. Stellen Sie sicher, dass die URL korrekt konfiguriert ist

A:

  1. Erhöhen Sie die Bildgrößenparameter

  2. Wählen Sie ein geeignetes Theme

  3. Optimieren Sie die Struktur des Mermaid-Codes

A:

  1. Überprüfen Sie die Netzwerkverbindungsgeschwindigkeit

  2. Erhöhen Sie die Umgebungsvariable REQUEST_TIMEOUT

  3. Vereinfachen Sie die Diagrammkomplexität

A:

  1. Stellen Sie sicher, dass der Theme-Name korrekt geschrieben ist

  2. Überprüfen Sie, ob das Theme unterstützt wird

  3. Versuchen Sie einen anderen Theme-Namen

A:

  1. Verwenden Sie den Parameter background_color

  2. Format: Hexadezimaler Farbcode (z. B. #FFFFFF)

  3. Wird nur für einige Ausgabeformate unterstützt


Technische Austauschgruppe

Treten Sie gerne der technischen Austauschgruppe bei, um Ihre Erfahrungen und Feedback zu teilen:

Technische Austauschgruppe


Autorenkontakt

WeChat-QR-Code


Spenden

Wenn dieses Projekt für Sie hilfreich ist, lade ich Sie gerne auf einen Kaffee ein ☕

WeChat Pay

WeChat Pay


Star-Historie

Wenn Ihnen das Projekt gefällt, freuen wir uns über einen Star ⭐

Star History Chart


Lizenz

MIT-Lizenz


Änderungsprotokoll

v0.1.0 (aktuelle Version)

  • ✅ Erstveröffentlichung

  • ✅ Unterstützt Mehrformat-Ausgabe in PNG, JPG, SVG, PDF

  • ✅ Integriert vier Theme-Stile (default, dark, neutral, forest)

  • ✅ Bietet Syntaxvalidierung und Beispielressourcen

  • ✅ Unterstützt STDIO- und SSE-Dualmodus-Kommunikation

v0.0.3 (2025-07-21)

  • ✅ Erstveröffentlichung

  • ✅ Unterstützt Mehrformat-Diagrammkonvertierung

  • ✅ Syntaxvalidierungsfunktion

  • ✅ Beispielressourcenfunktion


Beitragsleitfaden

Wir freuen uns über Issues und Pull Requests zur Verbesserung dieses Projekts!

  1. Forken Sie dieses Repository

  2. Erstellen Sie einen Feature-Branch: git checkout -b feature/amazing-feature

  3. Committen Sie Ihre Änderungen: git commit -m 'Add amazing feature'

  4. Pushen Sie zum Branch: git push origin feature/amazing-feature

  5. Reichen Sie einen Pull Request ein


Hinweise

  • Die Diagrammgenerierung kann einige Sekunden dauern, bitte haben Sie Geduld

  • Stellen Sie sicher, dass die Netzwerkverbindung funktioniert, da der Dienst auf die Online-API von mermaid.ink angewiesen ist

  • Die generierten Bilddaten werden im base64-Format zurückgegeben

  • Komplexe Diagramme können längere Generierungszeiten erfordern


Viel Spaß beim Erstellen wunderschöner Diagramme mit Mermaid! 🎨✨

Available Tools

3 tools
convert_mermaid_to_imageA
将 Mermaid 图表代码转换为多种格式的图像(PNG、JPG、PDF、SVG)。

参数:
    mermaid_code: 要转换的 Mermaid 图表语法代码
    output_format: 输出格式 - png、jpg、svg 或 pdf(默认:png)
    theme: 视觉主题 - default、dark、neutral 或 forest(默认:default)
    background_color: 背景颜色,十六进制代码(如 FF0000)或带 ! 前缀的命名颜色(如 !white)
    width: 图像宽度(像素,可选)
    height: 图像高度(像素,可选)

返回:
    包含转换后图像数据和元数据的字典

Inputs: mermaid_code (required), output_format, theme, background_color, +2 more. Returns: result

get_supported_optionsA
获取转换器支持的选项,如图表主题和输出格式。

返回:
    一个包含支持的主题和格式列表的字典。

Inputs: no named parameters. Returns: result

validate_mermaid_syntaxB
通过尝试简单转换来验证 Mermaid 图表语法。

参数:
    mermaid_code: 要验证的 Mermaid 图表语法代码

返回:
    包含验证结果的字典

Inputs: mermaid_code (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: convert_mermaid_to_image handles the core conversion functionality, get_supported_options provides metadata about available options, and validate_mermaid_syntax performs syntax validation. There is no overlap or ambiguity between these three functions.

    Naming Consistency5/5

    All tools follow a consistent snake_case naming pattern with clear verb-action structure: convert_mermaid_to_image, get_supported_options, and validate_mermaid_syntax. The naming is predictable and follows the same convention throughout.

    Tool Count4/5

    Three tools is a reasonable number for a Mermaid diagram conversion server, though it feels slightly minimal. The tools cover the essential operations (convert, validate, get options), but additional utilities like listing available themes or handling diagram editing might enhance completeness.

    Completeness4/5

    The tool set covers the core Mermaid conversion workflow well: conversion, syntax validation, and option discovery. Minor gaps include operations like batch conversion, diagram editing utilities, or theme management, but agents can work effectively with the provided tools for most use cases.

    Related MCP Connectors

    Related MCP Servers