Mermaid MCP Server

Mermaid MCP サーバー

Mermaid ダイアグラムを PNG 画像または SVG ファイルに変換する Model Context Protocol（MCP）サーバーです。このサーバーを使うと、AI アシスタントやその他のアプリケーションで、Mermaid の Markdown 構文を使用してテキストの説明から視覚的なダイアグラムを生成できます。

機能

• Mermaid のダイアグラムコードを PNG 画像または SVG ファイルに変換します
• 複数のダイアグラムテーマに対応します（default、forest、dark、neutral）
• 背景色をカスタマイズできます
• Puppeteer を使用して、高品質なヘッドレスブラウザー描画を行います
• MCP プロトコルを実装し、AI アシスタントとシームレスに連携します
• 柔軟な出力オプションに対応します。画像／SVG を直接返すか、ディスクに保存できます
• 詳細なエラーメッセージによるエラー処理に対応します

動作の仕組み

サーバーは Puppeteer を使用してヘッドレスブラウザーを起動し、Mermaid ダイアグラムを SVG に描画した後、必要に応じて描画したダイアグラムのスクリーンショットを撮影します。処理の流れは次のとおりです。

1. ヘッドレスブラウザーのインスタンスを起動します
2. Mermaid コードを含む HTML テンプレートを作成します
3. Mermaid.js ライブラリを読み込みます
4. ダイアグラムを SVG に描画します
5. SVG を直接保存するか、スクリーンショットを PNG として撮影します
6. 画像／SVG を直接返すか、ディスクに保存します

ビルド

npx tsc

使い方

Claude desktop で使用する

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["-y", "@peng-shawn/mermaid-mcp-server"]
    }
  }
}

Cursor および Cline で使用する

env CONTENT_IMAGE_SUPPORTED=false npx -y @peng-shawn/mermaid-mcp-server

./diagrams の下に Mermaid ダイアグラムの一覧があります。これらは Cursor エージェントを使って、次のプロンプトで作成されています：「Mermaid ダイアグラムを生成し、renderMermaidPng の仕組みを説明する別の diagrams フォルダーに保存してください」

インスペクターで実行する

テストとデバッグのために、インスペクターを使用してサーバーを実行します。

npx @modelcontextprotocol/inspector node dist/index.js

サーバーが起動し、MCP プロトコルメッセージを stdio で受け付けます。

インスペクターの詳細については、こちらをご覧ください。

Smithery 経由でインストールする

Smithery 経由で Mermaid Diagram Generator を Claude Desktop に自動インストールするには、次の手順を実行します。

npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude

Docker および Smithery 環境

Docker コンテナ内（Smithery 経由を含む）で実行する場合は、Chrome の依存関係に対応する必要がある場合があります。

1. サーバーはデフォルトで Puppeteer にバンドルされたブラウザーを使用するようになりました

2. ブラウザー関連のエラーが発生した場合は、次の 2 つの方法があります。

   方法 1：Docker イメージのビルド時

   • Puppeteer のインストール時に PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true を設定します
   • Docker コンテナに Chrome／Chromium をインストールします
   • 実行時に PUPPETEER_EXECUTABLE_PATH を設定し、Chrome のインストール先を指定します

   方法 2：Puppeteer にバンドルされた Chrome を使用する

   • Docker コンテナに Chrome の実行に必要な依存関係が含まれていることを確認します
   • PUPPETEER_SKIP_CHROMIUM_DOWNLOAD を設定する必要はありません
   • コードはバンドルされたブラウザーを自動的に使用します

Smithery ユーザーは、最新バージョンを追加の設定なしで利用できるはずです。

API

サーバーは次の単一のツールを公開します。

• generate：Mermaid のダイアグラムコードを PNG 画像または SVG ファイルに変換します
  • パラメーター：
    • code：描画する Mermaid ダイアグラムコード
    • theme：（任意）ダイアグラムのテーマ。選択肢：「default」、「forest」、「dark」、「neutral」
    • backgroundColor：（任意）ダイアグラムの背景色。例：「white」、「transparent」、「#F0F0F0」
    • outputFormat：（任意）ダイアグラムの出力形式。選択肢：「png」、「svg」（デフォルトは「png」）
    • name：生成するファイルの名前（CONTENT_IMAGE_SUPPORTED=false の場合は必須）
    • folder：画像／SVG の保存先の絶対パス（CONTENT_IMAGE_SUPPORTED=false の場合は必須）

generate ツールの動作は、CONTENT_IMAGE_SUPPORTED 環境変数によって異なります。

• CONTENT_IMAGE_SUPPORTED=true（デフォルト）の場合：ツールは画像／SVG をレスポンスで直接返します
• CONTENT_IMAGE_SUPPORTED=false の場合：ツールは指定されたフォルダーに画像／SVG を保存し、ファイルパスを返します

環境変数

• CONTENT_IMAGE_SUPPORTED：画像をレスポンスで直接返すか、ディスクに保存するかを制御します
  • true（デフォルト）：画像をレスポンスで直接返します
  • false：画像をディスクに保存します。その場合、name と folder パラメーターが必要です

使用例

基本的な使い方

// Generate a flowchart with default settings
{
  "code": "flowchart TD\n    A[Start] --> B{Is it?}\n    B -->|Yes| C[OK]\n    B -->|No| D[End]"
}

テーマと背景色を指定する

// Generate a sequence diagram with forest theme and light gray background
{
  "code": "sequenceDiagram\n    Alice->>John: Hello John, how are you?\n    John-->>Alice: Great!",
  "theme": "forest",
  "backgroundColor": "#F0F0F0"
}

ディスクに保存する場合（CONTENT_IMAGE_SUPPORTED=false）

// Generate a class diagram and save it to disk as PNG
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

SVG 出力を生成する

// Generate a state diagram as SVG
{
  "code": "stateDiagram-v2\n    [*] --> Still\n    Still --> [*]\n    Still --> Moving\n    Moving --> Still\n    Moving --> Crash\n    Crash --> [*]",
  "outputFormat": "svg",
  "name": "state_diagram",
  "folder": "/path/to/diagrams"
}

FAQ

Claude のデスクトップアプリは、すでにキャンバスで mermaid に対応しているのでは？

はい。ただし、theme と backgroundColor のオプションには対応していません。また、専用サーバーがあれば、さまざまな MCP クライアントで mermaid 図を簡単に作成できます。

Cursor で使用する場合、CONTENT_IMAGE_SUPPORTED=false を指定する必要があるのはなぜですか？

Cursor は、レスポンス内のインライン画像にまだ対応していないためです。

公開

このプロジェクトでは、GitHub Actions を使用して npm への公開プロセスを自動化しています。

方法 1：リリーススクリプトを使用する（推奨）

1. すべての変更をコミットしてプッシュしたことを確認します

2. 特定のバージョン番号、またはセマンティックバージョンの更新を指定してリリーススクリプトを実行します

   # Using a specific version number
   npm run release 0.1.4
   
   # Using semantic version increments
   npm run release patch  # Increments the patch version (e.g., 0.1.3 → 0.1.4)
   npm run release minor  # Increments the minor version (e.g., 0.1.3 → 0.2.0)
   npm run release major  # Increments the major version (e.g., 0.1.3 → 1.0.0)
   

3. スクリプトは次の処理を行います

   • バージョン形式またはセマンティックバージョンの更新を検証します
   • main ブランチにいることを確認します
   • ファイル間のバージョン不一致を検出して警告します
   • すべてのバージョン参照（package.json、package-lock.json、index.ts）を一貫して更新します
   • すべてのバージョン変更を含む単一のコミットを作成します
   • git タグを作成してプッシュします
   • その後、GitHub ワークフローが自動的にビルドして npm に公開します

方法 2：手動で行う

1. コードを更新して変更をコミットします
2. バージョン番号を指定して新しいタグを作成し、プッシュします

   git tag v0.1.4  # Use the appropriate version number
   git push origin v0.1.4
   

3. GitHub ワークフローが自動的に次の処理を行います
   • プロジェクトをビルドします
   • タグのバージョンで npm に公開します

注：GitHub リポジトリの設定で NPM_TOKEN シークレットを設定する必要があります。設定方法は次のとおりです

1. 公開権限を持つ npm アクセストークンを生成します
2. GitHub リポジトリで「Settings → Secrets and variables → Actions」に移動します
3. NPM_TOKEN という名前の新しいリポジトリシークレットを作成し、値に npm トークンを設定します

バッジ

ライセンス

MIT