ClaudeでMermaidの図を描くとき、
「MermaidMCPを導入してClaude自身に画像を確認させたほうが精度が上がるのでは？」
と思い、実際に検証してみた。
結論から言うと、
普段使いならMermaidMCPはいらない。Claude単体（MCPなし）で十分だった。
計23種類の図を描かせて比較したところ、以下のことが分かった。
- 精度：Claude単体でも初回エラーゼロ率は95.7%。主要な図はMCPあり・なしで出力コードが完全一致した
- コスト：MCPで視覚確認を挟むと、画像処理の分トークン消費量が約13倍に跳ね上がる
- 使いどころ：普段はいらないが、図が大量にある場合や、複雑なレイアウトで修正の手間を完全に省きたい場面なら入れる価値がある
MCPを入れると何が変わるのか、導入する価値はあるのか。実際に試して分かった違いをまとめた。
Mermaid.jsとは
Mermaidについて知っている人は読み飛ばしてください。
Mermaid.jsは、テキスト（コード）を書くだけでダイアグラムやチャートを自動生成できるJavaScriptライブラリだ。
通常の作図ツールのようにマウスで図形を配置したり線を引いたりする必要がなく、テキストエディタだけで作図が完結する。Markdownファイルの中に書いた mermaid コードブロックを、VS Code・GitHub・Notionなどの対応ビューアが自動検出して図に変換してくれる仕組みだ。
Gitでバージョン管理できる・コピペで共有できる・環境を選ばないといった利点があり、設計書や仕様書をMarkdownで管理しているプロジェクトとの相性が非常に良い。
たとえば以下のように書くだけで、フローチャートになる。
graph TD
A[開始] --> B{条件}
B -->|Yes| C[処理]
B -->|No| D[終了]
対応している記法はさまざまにあり、主なものは次の通りだ。
- フローチャート（縦型・横型）
- シーケンス図（処理の流れを時系列で表現）
- ER図（データベース設計）
- 状態遷移図
- クラス図（オブジェクト指向設計）
- ガントチャート
- Gitのブランチ・コミット構造の可視化
- マインドマップ
- タイムライン図
この他にもいろいろな図に対応している。
なぜ検証したか
社内プロジェクトでシステム設計図を書いて内容を理解したい場面があり、そのときMarkdownで各種の図を書けるMermaid記法を知った。
同時期に、AI活用の一環としてMCPを使った業務効率化を進めようとしており、「MermaidMCPを導入したほうがClaudeの精度が上がるのではないか」という案が浮かんだ。
Claude単体でも「Mermaidで図を描いて」と指示すれば図を描ける。ただ、MCPをつなげることで精度が上がるのか、導入あり・なしでどんな違いが出るのか、実際のところを知りたかった。
セキュリティ面での注意
Mermaidには関連サービスがいくつかあり、社内の機密情報を扱う場合は選択に注意が必要だ。
VS CodeなどでMermaidをレンダリングする分には、処理がエディタ内で完結するため問題ない。一方、「Mermaid Chart」のようなクラウド型サービスは図がサーバーに保存される仕組みなので、社内の設計書や仕様書を含む図を使うのは避けたほうがよい。
今回の検証はすべてローカルで完結する方法でやった。
MermaidMCPとは
MCP（Model Context Protocol）はAnthropicが策定したAIとツールを連携させる規格で、MermaidMCPはClaudeがMermaid図を描画・検証できるようにするMCPサーバーだ。
Claudeが mcp__mermaid-local__generate ツールを呼び出すと、ローカルでPNGレンダリングが実行される。環境変数 CONTENT_IMAGE_SUPPORTED=true を設定すると、ClaudeはそのPNG画像を直接視認できる。
MCPなしとの違いをひと言で言うと、「確認ループの主体が人間からClaudeに変わる」ことだ。
| 項目 | MCPなし | MCPあり |
|---|---|---|
| エラーの検出 | 人間がMarkdownビューアで確認 | Claudeが即時検出 |
| 修正の起点 | 人間がClaudeへ報告 | Claude自身が修正 |
| 外部通信（ローカル型） | なし | なし |
Claudeが選んだMCPパッケージ
MermaidMCPと名のつくnpmパッケージは複数あり、外部サーバーでレンダリングするものとローカルで完結するものがある。社内の機密情報を扱う都合上、外部通信が発生しないものを選ぶ必要があった。
「外部通信しないこと」という条件だけ渡して、選定もClaudeにやらせた（ClaudeCodeには作業報告書を書かせているので、詳細はその記録から把握している）。Claudeが選んできたのは @peng-shawn/mermaid-mcp-server（npm公開済み）だ。Puppeteerによるローカルレンダリングで外部API通信なし、npxで即時実行できる点が選定理由として報告されてきた。当初は mermaid-local-mcp（ryu1maniwa）を候補にしていたが、npmに未公開でnpxから実行できなかったため切り替えたとのことだった。
公式の「Mermaid Chart MCP」や「GittyBurstein/mermaid-mcp-server」は外部サーバーへの通信が発生するため、機密情報を扱うプロジェクトでは使えない。
検証の方法
次の順で進めた。
① MCPなしの状態でClaudeに図を描かせる
② MCPをインストールし、同じ図を再度Claudeに描かせる
③ ①と②の出力コードをdiffで比較させる
④ トークン消費量・作業の手間・品質をClaudeに考察させる
①を先に完了させてからMCPを導入したのは、MCPなしの状態でClaudeが何ができるかを先入観なく確認するためだ。最初からMCPを使ってしまうと、MCPなしの限界が測れなくなる。
セキュリティについては最初から制約を設けた。外部への通信が発生するMCPは使わないという条件でMCPサーバーを選んだ。
図の描画・インストール・diff比較・考察のすべての作業はClaudeが実行した。こちらは指示を出す役で、Claudeが作業して結果を報告してくる、という進め方だ。この記事の元になっている検証結果もClaudeが出力したものを見て、自分が判断・整理した。
第1回として代表的な6図（フローチャート・シーケンス図・ER図・状態遷移図・コンポーネント階層図・ディレクトリ構造図）を描かせた。差異がなくあっという間に終わってしまったため、当初は想定していなかったが、より精度の高い調査結果を得るためにさらに17図（gitGraph・classDiagram・gantt・timeline・mindmap・xychart-beta・pie・quadrantChart・requirementDiagram・block-beta と既存記法の応用7図）を追加した。
第1回検証、6図の結果
結論から言うと、MCPなしで書いたコードとMCPありで書いたコードは6図すべてで完全一致した。MCPによる視覚確認を経ても、修正は1回も発生しなかった。
正直、これは想定外だった。「視覚確認がないと信用できない」という先入観があったが、Claudeは確認なしでも正確なMermaid構文を生成していた。6図すべて初回エラーゼロというのが証拠だ。
ワークフローの違いは明確だった。
MCPなしのフロー:
Claude が Mermaid 構文を出力
↓
Markdown ビューア（VS Code等）で人間が確認
↓
エラーがあれば人間が Claude に報告
↓
Claude が修正して再出力
MCPありのフロー:
Claude が Mermaid 構文を出力
↓
Claude が MCP ツールを呼び出す
↓
ローカルで PNG レンダリング
↓
Claude が PNG 画像を視認（エラー・崩れを即検出）
↓
問題なければ完了 / 問題あれば即修正して再描画
今回の6図では修正ループが発生しなかったため、MCPなしとMCPありの体感的な差は小さかった。差が出るのは次の検証からだ。
急遽追加した17図の検証
17図のうち16図が初回エラーゼロで描画できた。失敗したのは requirementDiagram の1図のみで、これはClaudeの知識の問題ではなく、使用したバージョンのMermaidのバグによるものだった（後述）。
第1回・第2回を通じた全体の初回エラーゼロ率は22/23図（95.7%）。
初めて試みた10種類の記法、結果はこうだ。
| 記法 | 結果 | 特記事項 |
|---|---|---|
| gitGraph | 初回成功 | ブランチ・コミット・マージが色分けで正確 |
| classDiagram | 初回成功 | 継承・依存関係が明確に描画 |
| gantt | 初回成功 | 現在日付ライン・マイルストーンも正確 |
| timeline | 初回成功 | セクションごとに色分けされ横展開 |
| mindmap | 初回成功 | インデントでツリー構造を表現 |
| xychart-beta | 初回成功 | bar と line を1つずつ指定する記法 |
| pie | 初回成功 | 比率・凡例・パーセント表示が自動生成 |
| quadrantChart | 初回成功 | 近接するとラベルが重なるのは仕様 |
| requirementDiagram | 失敗（3回試行） | 使用したMermaidのバグ（Claudeの書き方の問題ではない） |
| block-beta | 初回成功 | 比較的新しい記法だが安定動作 |
失敗した図について
MCPありで失敗した図は requirementDiagram というものだ。
requirementDiagram はMermaidに存在する記法で、要件定義の内容を図として表現する。要件間の関係（この機能にはこの要件が必要、など）をボックスと矢印でつないで可視化するイメージだ。
requirementDiagram
requirement ログイン機能 {
id: REQ-001
text: ログインできる
risk: High
verifyMethod: Test
}
ログイン機能 - traces -> セッション管理
Claudeの報告によると、今回使ったバージョンのMermaidには text: フィールドに日本語や複数単語を書くとパースエラーになるバグがあるらしい。Claudeが正しい構文で書いても必ずエラーになる状態で、書き方の問題ではなくツール側の不具合だということだった。
ちなみに、MCPなし版でもClaudeはコードを書いていた。ただ、それでは図を描画できなかった。MCPなしでは、Claudeがその正否を確認する手段がなく、エラーのあるコードがそのまま残った状態で終わっていた。MCPありだからこそ、描画を試みた時点でエラーを即座に検出し、その原因（text:フィールドの制約）まで特定できた。（ただし、MCPありでもなしでも、描画自体はいずれにしても失敗していた。）
そもそも requirementDiagram 自体がかなりマイナーな記法で、ネットで調べても日本語の解説記事や実践例があまりない。今回はたまたま検証対象に含めたことで遭遇したが、普段使う記法ではないのであまり気にしなくてよいと思った。
トークン消費量の実測値
23図の検証を通じたトークン消費量の合計を記録した（推定値）。
| MCPなし | MCPあり | 差分 | |
|---|---|---|---|
| 第1回（6図） | 約1,200 | 約16,200 | +15,000 |
| 第2回（17図） | 約3,400 | 約44,900 | +41,500 |
| 合計（23図） | 約4,600 | 約61,100 | +56,500 |
差分の大半はPNG画像のbase64データが占める。図の解像度・複雑さで変動するが、1図あたり平均2,000トークン程度の増加だ。
6図程度では大きな問題にはならないが、50図・100図と増えるにつれてコスト差が拡大する。コンテキストが画像データで膨らむと、パフォーマンスや費用にも響いてくる。
セットアップの実録
セットアップもClaudeに任せた。「インストールしてMCPに登録して」と指示を出すと、Claudeがパッケージを選定してコマンドを実行し、設定ファイルへの登録まで自分でやった。
ただ正直、Claudeが作業している間は不安だった。どれだけ時間がかかっていても外からは進捗が見えない。エラーが起きていてもClaudeはひたすら作業を続けている。「ちゃんと動いているのか」がわからないまま、ただ見守るしかない時間が続いた。
インストール手順
参考までに、Claudeが実行したコマンドの記録だ。
# mermaid-cli のグローバルインストール
npm install -g @mermaid-js/mermaid-cli
# MermaidMCP サーバーのインストール
npm install -g @peng-shawn/mermaid-mcp-server
# Claude Code へ MCP として登録
claude mcp add mermaid-local \
-e CONTENT_IMAGE_SUPPORTED=true \
-- <mermaid-mcp-server.cmd のフルパス>
mermaid-cliのインストールに約50秒（Puppeteer/Chromium含む186パッケージ）かかった。Chromiumのダウンロード（約170MB）が大半を占めるため、回線が遅い環境では数分かかることがある。
インストールに時間がかかった要因のひとつが、Windows環境でのトラブルだった。Claudeの報告によると、UNCパス問題というものが発生していたとのことだった。
使い分けの判断基準
結果から見ると、使い分けはこうなる。
MCPなしでよい場合:
- 基本どの場合でもOK
- トークンや時間を節約したい
MCPありでもよい場合:
- 作成する図が大量
- 複雑な構文を多用する
- 修正ループが発生しやすい複雑なレイアウトを作成する
- 「Claudeが実際に確認した」という品質保証が成果物として必要
今回のセットアップは約26分かかった（Claude作業分6分 + トラブルシューティング20分）。ただ一度設定してしまえば以降は使い回せるため、図の多いプロジェクトでは長期的に元が取れる。
結論
通常の使用であればMermaidMCPを使わなくてよい。
Claudeは視覚確認なしでも、Mermaidの主要な記法を正確に生成できる。23図の検証で初回エラーゼロ率は95.7%だった。セットアップに時間がかかる点とトークン消費が約13倍になる点を考えると、普通に図を描くぶんにはMCPなしで十分だ。
MCPを入れる価値があるとすれば、図の枚数が多い・複雑な構文を多用する・修正ループが発生しやすい、といった状況だ。ClaudeがPNG画像を自分で視認して確認できるので、エラーを人間が都度報告する手間が省ける。一度設定してしまえば使い回せるので、そういうプロジェクトなら入れる価値はある。