Skip to main content
Glama
wwwzhouhui

Mermaid MCP Server

by wwwzhouhui

Mermaid MCP Server

Model Context Protocol (MCP) に基づく Mermaid 図表変換サーバー。AI クライアントに強力な図表生成機能を提供します

License Python MCP UV


プロジェクト紹介

Mermaid MCP Server は、Model Context Protocol (MCP) に基づく専門的な Mermaid 図表変換サーバーであり、AI クライアントに強力な図表生成機能を提供します。このプロジェクトは、Mermaid 図表コードを複数の形式の画像ファイル(PNG、JPG、SVG、PDF)に変換することができ、MCP プロトコルをサポートするさまざまな AI クライアントで高品質な図表を簡単に生成できます。

コア機能

  • 多形式出力: PNG、JPG、SVG、PDF など複数の画像形式をサポート

  • テーマカスタマイズ: default、dark、neutral、forest の4つの美しいテーマを内蔵

  • カスタムオプション: 背景色、画像サイズなどのパラメータをカスタマイズ可能

  • 構文検証: リアルタイムの Mermaid 構文検証機能を提供

  • サンプルリソース: 豊富な図表タイプのサンプルコードを内蔵

  • エラーハンドリング: 充実したエラー処理メカニズムと分かりやすいエラーメッセージ

  • STDIO/SSE デュアルモード: STDIO と SSE の2つの通信モードをサポート

  • uv パッケージ管理: 超高速の uv パッケージマネージャーを使用


Related MCP server: mcp-mermaid-validator

機能一覧

機能名

機能説明

技術スタック

ステータス

図表変換

Mermaid コードを画像に変換

mermaid.ink API

✅ 安定

多形式出力

PNG/JPG/SVG/PDF

requests + base64

✅ 安定

テーマカスタマイズ

4つの内蔵テーマ

mermaid.ink

✅ 安定

構文検証

リアルタイム構文チェック

mermaid-cli

✅ 安定

サンプルリソース

豊富な図表サンプル

静的リソース

✅ 安定

エラーハンドリング

充実したエラーメッセージ

Python 例外処理

✅ 安定

MCP プロトコル

Model Context Protocol

mcp[cli]

✅ 安定

SSE モード

Server-Sent Events

FastAPI + Uvicorn

✅ 安定


技術アーキテクチャ

技術

バージョン

用途

Python

3.12+

主要開発言語

MCP

1.9+

Model Context Protocol

FastAPI

0.104+

Web フレームワーク(SSE モード)

Uvicorn

0.24+

ASGI サーバー

requests

2.31+

HTTP クライアント

uv

latest

Python パッケージマネージャー

通信アーキテクチャ

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

インストール手順

環境要件

  • Python 3.12+

  • uv パッケージマネージャー(推奨)

依存関係のインストール

方法1:uv を使用したインストール(推奨)

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

# 安装依赖
uv sync

方法2:pip を使用したインストール

pip install -r requirements.txt

使用方法

クライアント設定

Cursor 設定

~/.cursor/mcp.json ファイルに以下の設定を追加します:

STDIO モード(推奨)

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

SSE モード

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

Cherry Studio 設定

  1. Cherry Studio を開く

  2. 設定 → MCP Servers → サーバーを追加 に移動

  3. パラメータを設定:

    • 名前: mermaid-mcp-server-png-pdf-jpg-svg

    • 説明: Mermaid 図表生成サービス

    • タイプ: STDIO

    • コマンド: uvx

    • パラメータ: mermaid-mcp-server-png-pdf-jpg-svg

  4. 保存して有効化

Cherry Studio 設定例

Claude Desktop 設定

claude_desktop_config.json ファイルに以下を追加:

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

Continue.dev 設定

config.json ファイルに以下を追加:

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

サービスの起動

STDIO モード(デスクトップクライアントに推奨)

uv run python main.py

SSE モード(ネットワーク接続用)

uv run python main.py --sse

設定説明

環境変数の設定

変数名

説明

デフォルト値

HOST

サーバーアドレス

0.0.0.0

PORT

サーバーポート

8003

LOG_LEVEL

ログレベル

INFO

MERMAID_API_BASE_URL

Mermaid API アドレス

https://mermaid.ink

REQUEST_TIMEOUT

リクエストタイムアウト(秒)

30

DEBUG

デバッグモード

false

DEVELOPMENT_MODE

開発モード

false


利用可能なツール

1. convert_mermaid_to_image

Mermaid 図表コードを複数の形式の画像ファイルに変換します

パラメータ

  • mermaid_code (string): Mermaid 図表コード

  • output_format (string, オプション): 出力形式。png、jpg、svg、pdf をサポート。デフォルトは "png"

  • theme (string, オプション): テーマスタイル。default、dark、neutral、forest をサポート。デフォルトは "default"

  • background_color (string, オプション): 背景色。16進数カラーコード

  • width (number, オプション): 画像の幅(ピクセル)

  • height (number, オプション): 画像の高さ(ピクセル)

サポートされる出力形式: PNG、JPG、SVG、PDF

2. validate_mermaid_syntax

Mermaid 図表コードの構文の正確性を検証します

パラメータ

  • mermaid_code (string): 検証が必要な Mermaid 図表コード

戻り値

  • valid (boolean): 検証に合格したかどうか

  • error_message (string): エラーメッセージ(検証に失敗した場合)

3. get_supported_options

コンバーターがサポートするオプションを取得します

戻り値

  • themes (array): サポートされるテーマのリスト

  • formats (array): サポートされる形式のリスト


サポートされる図表タイプ

  • フローチャート (Flowchart): プロセスやアルゴリズムの表現に使用

  • シーケンス図 (Sequence Diagram): オブジェクト間の相互作用の表現に使用

  • ガントチャート (Gantt Chart): プロジェクト進捗管理に使用

  • 円グラフ (Pie Chart): データの割合の表現に使用

  • Git グラフ (Git Graph): Git コミット履歴の表現に使用

  • マインドマップ (Mind Map): 知識構造の表現に使用

  • クラス図 (Class Diagram): クラス構造の表現に使用


使用例

フローチャートの例

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

シーケンス図の例

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

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

構文検証の例

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

リソースサンプル

図表サンプルの取得

以下のリソース URI を使用して、さまざまなタイプの図表サンプルを取得できます:

  • mermaid://examples/flowchart - フローチャートのサンプル

  • mermaid://examples/sequence - シーケンス図のサンプル

  • mermaid://examples/gantt - ガントチャートのサンプル

  • mermaid://examples/pie - 円グラフのサンプル

  • mermaid://examples/gitgraph - Git グラフのサンプル

  • mermaid://examples/mindmap - マインドマップのサンプル

  • mermaid://examples/class - クラス図のサンプル


プロジェクト構造

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

開発ガイド

ローカル開発

# 克隆仓库
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

デバッグモード

詳細なログ出力を有効にする:

export LOG_LEVEL=DEBUG
uv run python main.py

よくある質問

A:

  1. ネットワーク接続とファイアウォール設定を確認

  2. mermaid.ink API にアクセスできることを確認

  3. プロキシ設定を確認

A:

  1. validate_mermaid_syntax ツールを使用して構文を確認

  2. Mermaid 公式ドキュメントを参照

  3. サンプルリソースのコードを使用

A:

  1. 図表の内容を簡素化

  2. 複数の小さな図表に分割

  3. 画像サイズのパラメータを調整

A:

  1. uv パッケージマネージャーをインストール:curl -LsSf https://astral.sh/uv/install.sh | sh

  2. または pip でパッケージをグローバルにインストール

  3. PATH 環境変数を確認

A:

  1. サービスが SSE モードで起動していることを確認

  2. ポート 8003 が使用中でないか確認

  3. URL 設定が正しいことを確認

A:

  1. 画像サイズのパラメータを増やす

  2. 適切なテーマを選択

  3. Mermaid コードの構造を最適化

A:

  1. ネットワーク接続速度を確認

  2. REQUEST_TIMEOUT 環境変数を増やす

  3. 図表の複雑さを簡素化

A:

  1. テーマ名のスペルが正しいことを確認

  2. そのテーマがサポートされているか確認

  3. 別のテーマ名を試す

A:

  1. background_color パラメータを使用

  2. 形式は16進数カラーコード(例:#FFFFFF)

  3. 一部の出力形式のみサポート


技術交流グループ

技術交流グループへの参加を歓迎します。使用体験やフィードバックを共有しましょう:

技術交流グループ


作者連絡先

微信QRコード


投げ銭

このプロジェクトが役に立ったなら、コーヒー一杯ごちそうしてください ☕

微信支付

微信支付


Star History

プロジェクトが良いと思ったら、Star を付けてください ⭐

Star History Chart


License

MIT License


更新履歴

v0.1.0 (現在のバージョン)

  • ✅ 初期バージョンリリース

  • ✅ PNG、JPG、SVG、PDF の多形式出力をサポート

  • ✅ 4つのテーマスタイル(default、dark、neutral、forest)を統合

  • ✅ 構文検証とサンプルリソース機能を提供

  • ✅ STDIO と SSE のデュアルモード通信をサポート

v0.0.3 (2025-07-21)

  • ✅ 初期バージョンリリース

  • ✅ 多形式の図表変換をサポート

  • ✅ 構文検証機能

  • ✅ サンプルリソース機能


貢献ガイド

Issue と Pull Request を歓迎します。このプロジェクトの改善にご協力ください!

  1. このリポジトリを Fork

  2. 機能ブランチを作成:git checkout -b feature/amazing-feature

  3. 変更をコミット:git commit -m 'Add amazing feature'

  4. ブランチにプッシュ:git push origin feature/amazing-feature

  5. Pull Request を送信


注意事項

  • 図表の生成には数秒かかる場合があります。お待ちください

  • ネットワーク接続が正常であることを確認してください。サービスは mermaid.ink のオンライン API に依存しています

  • 生成された画像データは base64 形式で返されます

  • 複雑な図表は生成により長い時間がかかる場合があります


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: 图像高度(像素,可选)

返回:
    包含转换后图像数据和元数据的字典
ParametersJSON Schema
NameRequiredDescriptionDefault
mermaid_codeYes
output_formatNopng
themeNodefault
background_colorNo
widthNo
heightNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries full burden. It mentions the tool converts code to images and returns a dictionary with data and metadata, but lacks details on error handling, performance (e.g., rate limits), authentication needs, or side effects. This is inadequate for a mutation tool with zero annotation coverage.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by a structured list of parameters and return value. Every sentence earns its place with no redundant information, making it efficient and well-organized.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's complexity (6 parameters, mutation operation) and no annotations, the description does well by detailing all parameters and noting the return structure. However, it lacks behavioral context like error cases or limitations. The presence of an output schema mitigates some gaps, but more completeness is needed for a mutation tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters5/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 0%, so the description must compensate. It provides detailed semantics for all 6 parameters beyond the schema, including explanations of mermaid_code, output_format options, theme options, background_color syntax, and optional width/height. This adds significant value over the bare schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the specific action ('将 Mermaid 图表代码转换为多种格式的图像') with the resource (Mermaid chart code) and distinguishes from siblings by focusing on conversion rather than validation or option retrieval. It explicitly lists the output formats, making the purpose unambiguous.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage by specifying what the tool does, but does not explicitly state when to use it versus alternatives like validate_mermaid_syntax or get_supported_options. No guidance on prerequisites or exclusions is provided, leaving usage context partially inferred.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool returns a dictionary with lists of supported themes and formats, which adds behavioral context beyond the input schema (which has no parameters). However, it doesn't cover other traits like performance, error handling, or authentication needs, leaving gaps in transparency for a tool with no annotation support.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is highly concise and well-structured: two sentences that directly state the purpose and return value, with no wasted words. It's front-loaded with the core function, and every sentence adds essential information, making it efficient for an agent to parse.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (0 parameters, no annotations, but with an output schema), the description is reasonably complete. It explains what the tool does and the return format, which complements the output schema. However, it lacks usage context and some behavioral details, preventing a perfect score despite the structured support.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The tool has 0 parameters, and the input schema description coverage is 100% (with an empty schema). The description doesn't need to add parameter semantics, so it appropriately focuses on the return value. Since there are no parameters to document, a baseline score of 4 is justified, as the description doesn't introduce confusion or redundancy.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose: '获取转换器支持的选项,如图表主题和输出格式' (Get converter-supported options, such as chart themes and output formats). It specifies both the action ('获取' - get) and the resource ('支持的选项' - supported options), with concrete examples. However, it doesn't explicitly differentiate from sibling tools like 'convert_mermaid_to_image' or 'validate_mermaid_syntax', which prevents a score of 5.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or suggest scenarios where this tool is appropriate (e.g., before conversion to check available options). Without any usage context or exclusions, it relies on implicit understanding, which is insufficient for clear agent decision-making.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

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

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

返回:
    包含验证结果的字典
ParametersJSON Schema
NameRequiredDescriptionDefault
mermaid_codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions '尝试简单转换' (attempting simple conversion) as the validation method, which implies a read-only, non-destructive operation, but doesn't clarify error handling, performance implications, or what '简单转换' entails. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise and well-structured: a purpose statement followed by clear parameter and return sections in bullet-like format. Every sentence earns its place without redundancy, and it's front-loaded with the core functionality. The bilingual presentation (Chinese purpose, English labels) is efficient for clarity.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the tool's low complexity (single parameter, no nested objects) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers purpose, parameter semantics, and return type at a high level. However, it lacks usage guidelines and detailed behavioral context, which are minor gaps in this simple validation context.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The description explicitly documents the single parameter 'mermaid_code' as '要验证的 Mermaid 图表语法代码' (Mermaid diagram syntax code to validate), adding meaning beyond the schema's basic title 'Mermaid Code'. However, with schema description coverage at 0%, it doesn't provide format details, constraints, or examples. The baseline is 3 since it compensates somewhat but not fully for the schema's lack of descriptions.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool's purpose as '验证 Mermaid 图表语法' (validate Mermaid diagram syntax) and specifies the method '通过尝试简单转换' (by attempting simple conversion). It distinguishes from sibling tools like 'convert_mermaid_to_image' by focusing on validation rather than conversion to image format. However, it doesn't explicitly differentiate from 'get_supported_options' which might relate to syntax options.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools 'convert_mermaid_to_image' or 'get_supported_options', nor does it specify scenarios where validation is preferred over direct conversion or option checking. There's no indication of prerequisites or exclusions for usage.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

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

  1. 3 tool updates
    • First observedconvert_mermaid_to_image
    • First observedget_supported_options
    • First observedvalidate_mermaid_syntax

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.

Maintenance

ActivityActive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers