Claude×Mermaidの使い方｜図解生成からMCPプレビューまで

Mermaid とは — テキストで図を描く記法

Mermaid は、Markdown のコードブロック内に宣言的なテキストを書くだけで図を描画できるオープンソースのダイアグラム作成ツールです。たとえば次の 3 行だけでフローチャートが完成します。

graph TD
  A[要件定義] --> B[実装]
  B --> C[レビュー]

対応する図の種類は幅広く、フローチャート・シーケンス図・ステート図・クラス図・ER 図・ガントチャートなどを 1 つの記法体系でカバーします。GitHub や Notion、多くの技術ドキュメントツールが標準でレンダリングに対応しているため、エンジニアの設計資料・README・仕様書で事実上の標準になりつつあります。

Claude が Mermaid と相性抜群な理由

Claude は GitHub 上のリポジトリや技術文書を大量に学習しているため、Mermaid 記法を「構文として書ける」だけでなく「意味的に理解」できます(MindStudio の解説より)。この特性が次の 2 方向で効きます。

1. 生成方向: 「この処理の流れをシーケンス図にして」と自然言語で頼むだけで、正しい Mermaid コードを出力できる
2. 読解方向: 指示文の中に Mermaid 図を埋め込んでおくと、Claude が散文の説明と同等以上の精度でプロセスを把握できる

つまり Claude にとって Mermaid は「出力フォーマット」であると同時に「入力フォーマット」でもあるのです。

claude.ai で Mermaid 図を作る基本

ブラウザ版 claude.ai では、Artifacts 機能を使えば生成した Mermaid 図をその場でプレビューできます。手順は次のとおりです。

1. チャットで「○○ の流れを Mermaid のフローチャートで図解して」と依頼する
2. 生成された図が Artifacts パネルにレンダリングされる
3. 「分岐を増やして」「縦方向のレイアウトにして」と会話で修正を重ねる
4. 完成したら Mermaid コードをコピーして README や設計書に貼り付ける

図そのものを画像で受け取るのではなく「テキストのコード」として受け取れるため、後から自分で編集でき、Git で差分管理もできるのが画像生成ツールとの決定的な違いです。

claude-mermaid MCP サーバーでライブプレビュー

Claude Code(ターミナル版)で Mermaid を本格的に使うなら、veelenga/claude-mermaid(MIT ライセンス)の導入がおすすめです。これは Claude Code に Mermaid のレンダリング機能を追加する MCP サーバーで、生成した図をブラウザに自動表示し、修正のたびに WebSocket 経由でライブリロードしてくれます。

主な機能は次のとおりです。

• 図を修正するたびにブラウザ表示が自動更新(ライブリロード)
• SVG / PNG / PDF の 3 形式で保存可能
• テーマ切り替え(default / forest / dark / neutral)
• パン・ズーム・リセット付きのインタラクティブプレビュー
• preview_id 指定で複数の図を同時に作業可能

claude-mermaid のインストール手順

公式 README で案内されている導入方法は 3 通りあります。最も簡単なのはプラグイン経由です。

Step 1: プラグインをインストールする

Claude Code のセッション内で次の 2 コマンドを実行します。

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

npm でグローバルインストールする方法(npm install -g claude-mermaid)や、リポジトリを clone してソースからビルドする方法も用意されています。

Step 2: 図の生成とプレビューを依頼する

インストール後は、Claude Code に「このモジュールの依存関係を Mermaid で図解してプレビューして」と頼むだけです。MCP サーバーが公開する mermaid_preview ツールが呼ばれ、ブラウザに図が表示されます。width・height・scale・background・theme などのパラメータも指定できます。

Step 3: 完成した図を保存する

仕上がりに満足したら「SVG で保存して」と伝えれば mermaid_save ツールでファイル出力されます。PNG や PDF を指定すれば資料貼り付け用の形式でも受け取れます。

応用: Mermaid 図でコンテキストを圧縮する

Mermaid は「図を描く」以外に、Claude への指示を効率化する道具としても注目されています。MindStudio の検証記事によると、複雑な条件分岐を含むワークフローの説明は散文だと 800〜1,500 トークンを要するのに対し、Mermaid 図なら 150〜350 トークンで同等の情報を伝達でき、約 3〜6 倍のトークン効率になるとされています。

Claude Code のカスタム指示ファイルにプロセスを記述する際、長い散文の代わりにフローチャートを 1 つ埋め込む構成にすると、コンテキスト消費を抑えつつ指示の曖昧さも減らせます。プロセスの種類ごとの図の使い分けは次が目安です。

• 条件分岐・判定ゲートがある手順 → フローチャート
• 複数システム間のやり取り → シーケンス図
• エラーハンドリングや状態遷移 → ステート図
• データ構造の関係 → クラス図 / ER 図

このときのコツは「ノードのラベルは短く保ち、詳細は図の外に書く」ことです。図に情報を詰め込みすぎると、かえって可読性とトークン効率の両方が落ちます。

つまずきやすいポイントと対処法

実際に使い始めると遭遇しがちな問題を 3 つ挙げます。

1. 構文エラーで図がレンダリングされない: Mermaid はノード名に使える文字に制約があります。日本語ラベルは A[日本語テキスト] のように角括弧で囲い、括弧やクォートを含むラベルは A["テキスト(補足)"] とダブルクォートで包むとエラーを回避できます。エラーが出たらそのままエラーメッセージを Claude に貼り付ければ、ほとんどの場合自己修正してくれます。
2. 巨大な図が読めない: 1 つの図にすべてを詰め込むより、「全体俯瞰の図」+「各部分の詳細図」に分割するよう Claude に依頼した方が実用的です。claude-mermaid なら preview_id を分けて複数の図を並行プレビューできます。
3. ブラウザプレビューが更新されない: claude-mermaid のライブリロードは WebSocket 接続が前提です。ブラウザタブを閉じてしまった場合は、再度プレビューを依頼すれば新しいタブで開き直されます。

まとめ — 設計の言語化に Mermaid を組み込もう

Claude × Mermaid の組み合わせは、「頭の中の構造を最速でドキュメント化する」ための実用的なワークフローです。claude.ai の Artifacts で気軽に図解する使い方から始め、Claude Code ユーザーは claude-mermaid MCP サーバーでライブプレビュー環境を整え、慣れてきたら指示ファイルへの図の埋め込みによるコンテキスト圧縮まで進む——という段階的な活用がおすすめです。

テキストで管理できる図は、コードと同じようにレビューでき、差分が追え、AI が読み書きできます。設計資料を「描く」から「書く」へ切り替える第一歩として、まずは身近な処理フローを 1 つ、Claude に図解させてみてください。

出典:

• veelenga/claude-mermaid - GitHub
• Mermaid 公式サイト
• How to Use Mermaid Diagrams in Claude Code Skills to Compress Context - MindStudio