Diagrams.so

@diagrams-so/mcp

Diagrams.so MCP サーバー — Claude Desktop、Claude Code、Cursor など、あらゆる MCP クライアントからクラウドアーキテクチャ図を生成、編集、管理できます。公開されている Diagrams.so API（/api/v2）を利用する、薄い stdio クライアントです。各ツールは REST 呼び出しを 1 回行います。

クイックスタート

Node ≥ 18 が必要です。API キーをコピーする必要はありません。ブラウザーで承認するだけで接続できます。

# 1. add the server to Claude Code
claude mcp add diagrams-so -- npx -y @diagrams-so/mcp

# 2. connect this machine (a browser opens, press Approve)
npx @diagrams-so/mcp login

クライアントを再起動してから、「AWS の 3 層 Web アプリの図を生成して、警告を表示して」と依頼してください。 まず 23 個のツールがすべて登録されていることを確認する場合は、/mcp を実行します。

頻繁に使いますか？ 一度インストールすれば、コマンドが短くなります。

npm i -g @diagrams-so/mcp
diagrams-so login

サーバーはデフォルトで本番環境（https://api.diagrams.so/api/v2）に接続します。 ローカルまたはセルフホスト可能な API を使うには、DIAGRAMS_API_BASE を指定してください。

CLI ではなく Claude Desktop や Cursor を使っていますか？ MCP クライアントに追加するをご覧ください。ワンクリックでターミナルを使わずにインストールしたい場合は、ワンクリックインストール（MCPB）をご覧ください。

ターミナルを一切使わない場合（Claude Desktop）

クライアントの設定（以下）にサーバーを追加し、DIAGRAMS_LOGIN_EMAIL にメールアドレスを設定してから、図を作成するよう依頼してください。マシンがまだ接続されていないため、最初のツール呼び出しでワンタイムのサインインコードがメールで送信され、リンクが返されます。リンクを開いてコードを入力し、Approve を押してから、もう一度依頼してください。インストールも入力も必要ありません。

Claude から図を生成する

login はマシンを接続するだけです。それ自体が何かを生成することはないため、ターミナルに入力する generate コマンドはありません。プロンプトはアシスタントの通常のチャットボックスに入力すると、アシスタントがツールを呼び出します。

クライアント	プロンプトを入力する場所
Claude Code	ターミナルのチャット。ほかの質問をする場所と同じです
Claude Desktop	通常のメッセージボックス
Cursor	チャットまたはコンポーザーパネル

MCP サーバーは起動時に読み込まれるため、追加した後にクライアントを再起動してください。 次に /mcp を実行し、diagrams-so に 23 個のツールが表示されていることを確認します。

あとは、自然な英語で依頼するだけです。

ALB、EC2 Auto Scaling、RDS Multi-AZ を備えた、3 層の AWS Web アプリを生成してください。 設計上の警告を表示してから、draw.io としてエクスポートしてください。

この一文を受けて、アシスタントは generate_diagram、次に get_warnings、最後に export_diagram を呼び出します。ツール名を指定したり、JSON を書いたりする必要はありません。

図ができたら、次のような依頼もできます。

警告に通信中の暗号化がないとあります。それを修正して、新しいスコアを表示してください。

ALB の前に CloudFront ディストリビューションを追加してください。

README に貼り付けられるよう、SVG として再エクスポートしてください。

どのプランでも、図の作成と編集は無制限です。従量課金はなく、分単位のレート制限のみがあります。有料プランでは、透かしなしと draw.io エクスポートが利用できます。無料プランの図は非公開にできます。

有料プランでは、アシスタントが保存する .drawio ファイルは、app.diagrams.net またはデスクトップアプリで開いて完全に編集できます。画像ではなく、実際の draw.io XML です。無料プランでは、代わりに透かし入りの画像（SVG）がツールから返され、その旨が表示されます。編集可能な draw.io ファイルには有料プランが必要です。

アシスタントをまったく使わずに利用したいですか？ diagrams.so/create では、同じ機能を Web ページから使えます。ボックスにプロンプトを入力するだけです。インストールも、login も、MCP も必要ありません。

ツール（23）

作成と変更（変更を伴う操作）

ツール	機能
generate_diagram	プロンプトから図を作成 → ID + 警告 + スコア + draw.io XML（有料）または透かし入り画像へのリンク（無料）
edit_diagram	自然言語による変更を適用（新しいバージョン）
fix_warning	Well-Architected の警告を1件解決
relayout_diagram	AI によるレイアウトの再配置（非同期。confirm=true で確認を要求）
import_diagram	既存の draw.io XML を新しい図としてインポート
update_diagram	名前変更／公開範囲の変更／XML の置換
revert_diagram	以前のバージョンに戻す
delete_diagram	図を論理削除（破壊的操作）
fork_template	公開図／ライブラリの図をアカウントにコピー（非公開）

読み取り

ツール	機能
get_diagram	図のスコア + XML（有料）または透かし入り画像へのリンク（無料）を取得
list_diagrams	自分の図を一覧表示（カーソルによるページネーション）
get_warnings	図に関する Well-Architected の指摘事項
export_diagram	生の svg（すべてのプランで利用可能。無料プランでは透かし入り）または drawio（有料。無料プランでは透かし入り SVG を取得）
list_versions	バージョン履歴（is_current を含む）
get_version	特定のバージョンのスコア + XML（有料）または透かし入り画像へのリンク（無料）を取得
get_relayout_status	非同期レイアウト変更ジョブの状態をポーリング
search_gallery	公開コミュニティと厳選ライブラリの図を検索
enhance_prompt	大まかなアイデアを詳細なプロンプトに変換
clarify_prompt	曖昧なプロンプトについて確認の質問を取得
get_usage	自分のプランと使用状況
get_usage_history	過去のタスク（アクション、図、利用環境）をフィルター付きで表示し、現在のセッションの集計も表示
whoami	アカウント、プラン、スコープ、ライブ／テストモード
list_capabilities	有効な図の種類／プロバイダー／エクスポート形式

すべてのプランですべてのツールを無制限に利用できます。delete は破壊的操作であり、relayout はレイアウトを置き換える前に confirm=true による確認を要求します。

CLI

コマンド

パッケージをインストールすると、diagrams-so が PATH に追加されます。長い名前の diagrams-so-mcp も引き続き使用でき、npx @diagrams-so/mcp <command> を使えば 何もインストールせずに実行できます。

npm i -g @diagrams-so/mcp

diagrams-so login          # connect this machine (a browser opens, press Approve)
diagrams-so whoami         # which account is this machine connected as
diagrams-so logout         # remove the local credential
diagrams-so install        # print client config to paste

環境変数

変数	必須	デフォルト
DIAGRAMS_API_KEY	❌	—（CI とヘッドレス環境専用。通常は login を使用）
DIAGRAMS_API_BASE	❌	https://api.diagrams.so/api/v2（本番環境。ローカル／セルフホスト環境用に上書き可能）
DIAGRAMS_API_TIMEOUT_MS	❌	450000（リクエストごとのセーフティネット。API のサーバー側タイムアウト全体の階層より長く設定）
DIAGRAMS_BROWSER	❌	—（login はデフォルトのブラウザーを開きます。Diagrams.so のセッションがデフォルト以外のブラウザーにある場合は、たとえば Google Chrome を設定してください）
DIAGRAMS_NO_BROWSER	❌	—（任意の値を設定すると、login がブラウザーを開かなくなります。URL は常に出力されます）
DIAGRAMS_NO_AUTO_LOGIN	❌	—（任意の値を設定すると、ツール内での接続を無効にします。未認証のツールは login の実行を促すだけになります）
DIAGRAMS_LOGIN_EMAIL	❌	—（ツール内接続に使用するアドレス。一度限りのサインインコードがこのアドレスにメールで届きます。未設定の場合、未認証のツールは接続を開始せず、代わりに login の実行を促します）

MCP クライアントに追加する

公開パッケージは npm から直接実行されるため、設定に入力するパスもキーもありません。npx @diagrams-so/mcp install を実行すると、使用するクライアント向けの設定ブロックが表示されます。

Claude Code（CLI）

claude mcp add diagrams-so -- npx -y @diagrams-so/mcp
npx @diagrams-so/mcp login

Claude Desktop / Cursor（claude_desktop_config.json / mcp.json）

{
  "mcpServers": {
    "diagrams-so": {
      "command": "npx",
      "args": ["-y", "@diagrams-so/mcp"]
      // optional: "env": { "DIAGRAMS_API_BASE": "http://localhost:8000/api/v2" } for a local API
    }
  }
}

npx @diagrams-so/mcp login を一度実行して接続するか、DIAGRAMS_LOGIN_EMAIL を設定している場合は図を依頼し、最初のツール呼び出しで表示されるリンクに従ってください（サインインコードはメールで届きます）。DIAGRAMS_API_KEY を設定するのは、ブラウザーを開けない CI とヘッドレスマシンの場合に限ってください。

クライアントを再起動し、次のように依頼してください。「AWS の3層ウェブアプリの図を生成して、警告を表示してください。」

ワンクリックインストール（MCPB）

最新リリースからdiagrams-so.mcpbをダウンロードし、Claude Desktopにドラッグしてください。ターミナルは不要です。また、APIキーを求められることもなくなりました。インストール後、初回使用時に最初のツール呼び出しで表示されるリンクをクリックして接続してください。

バンドルを自分でビルドするのはコントリビューター向けの手順です。ローカルでの開発を参照してください。

Smithery

サーバーはsmithery.ai/servers/diagrams-so/mcpに掲載されています。ここからインストールでき、パラメーターとともに23個すべてのツールを確認できます。

npx -y smithery mcp add diagrams-so/mcp

同じパッケージで、loginの手順も同じです。SmitheryがインストールするのはMCPBバンドルであり、npmパッケージではありません。そのため、表示されるバージョンはnpm dist-tagsではなくリリースに従います。

動作確認

DIAGRAMS_API_KEY=dgz_live_your_key node test-smoke.mjs

一連のフロー（接続 → ツール一覧の取得 → whoami → 生成 → 警告 → 修正 → エクスポート → エラー処理）をすべて実行します。

継続的インテグレーションとリリース

ワークフロー	トリガー	内容
CI（ci.yml）	プッシュまたはPRごと	Node 18/20/22でnpm ciとnpm run buildを実行し、その後、ビルド済みサーバーを起動して23個すべてのツールが登録されることを確認する無料のスモークテスト（scripts/ci-smoke.mjs）を実行します。API呼び出しはありません。
ライブスモーク（live-smoke.yml）	毎晩および手動	実際のAPIに対して、エンドツーエンドのフロー（test-smoke.mjs）全体を実行します。実際のAPIを呼び出すため、DIAGRAMS_API_KEYシークレットが設定されている場合にのみ実行されます。
リリース（release.yml）	タグvX.Y.Z	ビルド → npm prune --omit=dev → diagrams-so.mcpbをパッケージ化 → GitHub Releaseに添付します。NPM_TOKENシークレットが設定されている場合はnpmにも公開します。

リリースを作成する：

# bump "version" in package.json + manifest.json to match, commit, then:
git tag v1.2.0 && git push origin v1.2.0

タグはpackage.jsonのversionと一致する必要があります（ワークフローが検証します）。.mcpbバンドルはGitHub Releaseに表示されます。手動のworkflow_dispatchでは、公開せずにダウンロード可能なアーティファクトとして生成されるため、バンドルのテストに便利です。

リポジトリのシークレット／変数（任意）： DIAGRAMS_API_KEY（ライブスモーク）、NPM_TOKEN（npm公開）、DIAGRAMS_API_BASE変数（本番環境以外のライブスモークの接続先）。

注意事項

• stdoutはMCPの通信チャネルです — サーバーはstderrにのみログを出力します。
• エラーは、APIのcode、HTTPステータス、request_idを含む、整理されたMCPツールエラーとして返されます。
• サーバーが内部サービスやデータベースと通信することはありません。公開されている/api/v2のみを使用します。
• 長時間実行されるツールは、クライアントのタイムアウト後も実行を継続します。 実行中、generate / edit / fix / relayout / enhance_prompt / clarify_promptは10秒ごとにnotifications/progressを送信します。そのため、進行状況に応じてリクエストのタイムアウトをリセットするMCPクライアント（resetTimeoutOnProgress）では、SDKのデフォルトである60秒を超える生成処理が中断されません。クライアントが進行状況に応じてタイムアウトをリセットしない場合は、これらのツールの呼び出しごとのタイムアウトを延長してください。

ローカルでの開発

サーバー自体を変更する場合にのみ必要です。ユーザーはnpmからインストールしてください。詳しくはクイックスタートを参照してください。

git clone https://github.com/RedHold/diagrams-mcp-app-core.git
cd diagrams-mcp-app-core
npm install                  # installs deps and builds dist/ via the prepare hook
node scripts/ci-smoke.mjs    # all 23 tools register; no API calls

# point a client at your working copy
claude mcp add diagrams-so-dev -- node "$(pwd)/dist/index.js"

# build the MCPB bundle
npm run build && npx @anthropic-ai/mcpb pack

ライセンスと法的事項

• コード： Apache-2.0。NOTICE をご覧ください。
• サービス： このサーバーは Diagrams.so API のクライアントです。API の利用は 利用規約 と 利用ポリシー に従います。コードのライセンスは API 自体の利用権を付与するものではありません。
• プライバシー： サーバーはローカルで実行され、api.diagrams.so のみに接続し、テレメトリーは含まれていません。login で取得した認証情報は、所有者のみがアクセスできる権限で ~/.diagrams-so/credentials.json に保存されます。プライバシーポリシー をご覧ください。
• プラン： すべてのプランで、図の作成と編集は無制限ですが、1 分あたりのレート制限があります。有料プランでは透かしがなく、draw.io へのエクスポートが可能です。Free プランの図も非公開にできます。テストモードのキーを使用すると、実際のアカウントに対して操作が行われます。
• 商標： Diagrams.so と Diagrams.so のロゴは RedHold LLC の商標です。このライセンスでは、パッケージの出所を正確に説明する場合を除き、これらの使用は許可されていません。商標ポリシー をご覧ください。
• セキュリティ： 脆弱性は SECURITY.md に従って [email protected] へ報告してください。