Cloudcraft MCP

cloudcraft-mcp

Cloudcraft 用の非公式 Model Context Protocol（MCP）サーバーです。Claude Desktop やその他の MCP クライアントから、クラウドアーキテクチャのブループリントの一覧表示、読み込み、エクスポート、作成を行えます。

機能

MCP ホストに公開される 13 個のツール：

ツール	説明
whoami	設定されたキーに対応する Cloudcraft ユーザープロフィールを返します。
list_blueprints	アカウント内のすべてのブループリントを一覧表示します。
get_blueprint	ブループリントのすべてのノード／エッジを含む JSON を取得します。
create_blueprint	JSON ペイロードから新しいブループリントを作成します。
update_blueprint	既存のブループリントのペイロードを置き換えます。
delete_blueprint	ブループリントを削除します（取り消し不可）。
export_blueprint_image	ブループリントを PNG／SVG／PDF／mxgraph としてディスクにレンダリングします。
export_blueprint_budget	ブループリントのコスト見積もりを CSV／XLSX としてディスクにエクスポートします。
list_teams	アカウントに関連付けられたチームを一覧表示します。
list_aws_accounts	ライブスキャンのスナップショット用に接続された AWS アカウントを一覧表示します。
snapshot_aws	AWS の 1 つのリージョンをライブスキャンし、ブループリント JSON に変換します（filter／exclude は省略可能）。
list_azure_accounts	ライブスキャンのスナップショット用に接続された Azure アカウントを一覧表示します。
snapshot_azure	Azure の 1 つのリージョンをライブスキャンし、ブループリント JSON に変換します（filter／exclude は省略可能）。

必要条件

• 推奨される uvx および npm 起動方法で使用する uv
• npm 起動方法を使用する場合のみ Node.js 22+
• Cloudcraft API キー — https://app.cloudcraft.co/ → User settings → API keys で生成できます

インストール

アップグレードを意図的に行えるよう、クライアント設定では変更されないバージョンを使用してください。

配布方法	コマンド
PyPI / uvx	uvx --from cloudcraft-mcp==0.1.8 cloudcraft-mcp
pipx	pipx run --spec cloudcraft-mcp==0.1.8 cloudcraft-mcp
npm / npx	npx -y @hypark5540/[email protected]
Docker / GHCR	docker run --rm -i -e CLOUDCRAFT_API_KEY ghcr.io/hypark5540/cloudcraft-mcp:0.1.8
Claude Desktop	対応する GitHub リリースから cloudcraft-mcp.mcpb をダウンロード

uvx は PyPI パッケージから提供されます。uvx 専用のレジストリはありません。 npm パッケージにはバイト単位で同一の Python wheel が組み込まれており、uv を介して実行されるため、npm を使う場合は Node.js と uv の両方が必要です。postinstall フックでコードをダウンロードすることはありません。

チェックアウトしたリポジトリから開発する場合：

git clone https://github.com/hypark5540/cloudcraft-mcp.git
cd cloudcraft-mcp
export CLOUDCRAFT_API_KEY='your-key-here'
uv run --frozen cloudcraft-mcp   # Ctrl+C to exit

Claude Desktop との統合

uv をインストールし、Claude Desktop の設定に次のエントリを追加してください。利用可能な場合は Claude のシークレットストレージを使用してください。以下のリテラル値は、どの環境でも使える例にすぎません。

{
  "mcpServers": {
    "cloudcraft": {
      "command": "uv",
      "args": [
        "tool",
        "run",
        "--isolated",
        "--from",
        "cloudcraft-mcp==0.1.8",
        "cloudcraft-mcp"
      ],
      "env": {
        "CLOUDCRAFT_API_KEY": "your-key-here",
        "CLOUDCRAFT_ENABLE_WRITES": "false",
        "CLOUDCRAFT_ENABLE_DELETES": "false"
      }
    }
  }
}

Claude Desktop を再起動します。Developer タブに cloudcraft が接続済みとして表示されます。

Cursor、Gemini CLI、npm、Docker、MCPB の例については、クライアントのセットアップを参照してください。

環境変数

名前	必須	デフォルト	用途
CLOUDCRAFT_API_KEY	はい	—	API キー（Bearer）。Cloudcraft のユーザー設定で生成します。
CLOUDCRAFT_BASE_URL	いいえ	https://api.cloudcraft.co	プロキシや将来の API バージョン向けの上書き設定です。
CLOUDCRAFT_LOG_LEVEL	いいえ	WARNING	標準エラー出力のログ詳細度（DEBUG / INFO / WARNING / ERROR）。
CLOUDCRAFT_EXPORT_DIR	いいえ	非公開の一時サブディレクトリ	export_blueprint_image の出力先として使用できるディレクトリです。
CLOUDCRAFT_ENABLE_WRITES	いいえ	false	create_blueprint と update_blueprint を許可します。
CLOUDCRAFT_ENABLE_DELETES	いいえ	false	書き込みも有効な場合に削除を許可します。
CLOUDCRAFT_MAX_RESPONSE_BYTES	いいえ	26214400	メモリやディスクを使い果たす前に、サイズ超過の Cloudcraft レスポンスを拒否します。

使用例（Claude）

サーバーに接続したら、Claude に次のように依頼できます。

「Cloudcraft のブループリントを一覧表示して、それぞれが何を表しているか要約してください。」

「ブループリント f0086b32-... を PNG としてエクスポートして、デスクトップに保存してください。」

「今設計したアーキテクチャを使って、『Prod 2026』という名前の新しい Cloudcraft ブループリントを作成してください。」

「接続している AWS アカウントの ap-northeast-2 のスナップショットを、セキュリティグループを除外して作成してください。」

「ブループリント f0086b32-... の月次予算を EUR 建ての CSV としてエクスポートしてください。」

ブループリントのペイロード形式

create_blueprint / update_blueprint では、Cloudcraft の完全な data オブジェクトを受け付けます。最小限のペイロードは次のとおりです。

{
  "grid": "infinite",
  "projection": "isometric",
  "theme": {"base": "light"},
  "version": 6,
  "nodes": [
    {"id": "...", "type": "ec2", "mapPos": [3, 3], "region": "ap-northeast-2",
     "instanceType": "m7g", "instanceSize": "large", "platform": "linux"},
    {"id": "...", "type": "s3",  "mapPos": [1, 8], "region": "ap-northeast-2",
     "volumeType": "Standard", "dataGb": 100}
  ],
  "edges": [
    {"from": "...ec2-id...", "to": "...s3-id...", "type": "edge",
     "width": 2, "dashed": false, "endCap": "arrow"}
  ],
  "groups": [], "surfaces": [], "text": [], "icons": [],
  "connectors": [], "images": [], "disabledLayers": [],
  "shareDocs": false
}

ノードタイプの全カタログとサービス固有のフィールドについては、Cloudcraft の API ドキュメントを参照してください。

開発

uv sync --extra dev
uv run pytest            # unit tests (no network)
uv run ruff check .      # lint
uv run mypy src          # type check

テストでは respx を使って HTTP レイヤーをモックするため、API キーは不要です。

カバレッジ

CI は Python 3.12 のマトリックスセルから coverage.xml を Codecov にアップロードします。プロジェクトのゲートは 80% 以上です。全体またはパッチのカバレッジがこの基準を 1 パーセンテージポイントを超えて下回る PR は、Codecov チェック（codecov.yml）で失敗します。

同じレポートをローカルで実行するには、次のコマンドを使います。

uv run pytest --cov=cloudcraft_mcp --cov-report=term-missing --cov-report=xml

プロジェクト構成

cloudcraft-mcp/
├── src/cloudcraft_mcp/
│   ├── __init__.py
│   ├── __main__.py         # python -m cloudcraft_mcp
│   ├── server.py           # MCP tool definitions (FastMCP)
│   ├── client.py           # CloudcraftClient — async httpx wrapper
│   ├── types.py            # TypedDicts for blueprint payloads
│   └── py.typed
├── tests/
│   └── test_client.py
├── bin/cloudcraft-mcp.mjs # npm-to-uv launcher
├── mcpb/manifest.json     # Claude Desktop bundle metadata
├── server.json            # official MCP Registry metadata
├── package.json           # npm distribution
├── server.py               # back-compat shim -> cloudcraft_mcp.server:main
├── pyproject.toml
├── LICENSE
└── README.md

設計上の注意点

• トランスポートとロジックの分離。 client.py は、MCP ランタイムを取り込まずにスクリプトや CLI ツールからインポートできる、通常の非同期 HTTP クライアントです。server.py は MCP ツールのインターフェースのみを担当します。
• Bearer トークン認証。 Cloudcraft の API は Authorization: Bearer <key>（Apikey ではありません）を要求します。クライアントがこれを自動的に設定します。
• プロセス引数にシークレットを含めない。 API キーは CLOUDCRAFT_API_KEY から読み込みます。コマンドラインで渡さないでください。
• 実装は一つ。 PyPI、npm、MCPB、コンテナは、言語ごとのフォークを個別に維持せず、同じバージョン管理された Python パッケージを起動します。
• エラーの扱い。 2xx 以外のレスポンスでは、ステータスと本文を保持した CloudcraftError が発生します。MCP の境界で RuntimeError に再ラップされるため、Claude に読みやすいメッセージが表示されます。

セキュリティ

• API キーは、Cloudcraft アカウントへの完全な読み取り／書き込み権限を付与します。秘密情報として扱い、定期的にローテーションしてください。
• MCP ツールのアノテーションは、読み取り専用のツールと変更・破壊を伴うツールを示すため、対応するホストでより適切な承認プロンプトを表示できます。これらのアノテーションはヒントであり、強制する仕組みではありません。
• 環境変数によるゲートと、削除時の正確な ID の確認は、多層防御のためのものであり、 対話的な承認ワークフローではありません。MCP ホストのツール承認 UX は有効にしておいてください。
• Cloudcraft への変更はデフォルトで無効になっています。作成／更新アクセスが必要なクライアントに限り、CLOUDCRAFT_ENABLE_WRITES=true を設定してください。削除にはさらに、CLOUDCRAFT_ENABLE_DELETES=true の設定と、各呼び出しでのブループリント ID の正確な再指定が必要です。
• delete_blueprint は取り消せません。Claude に削除を依頼するときは、対象の ID を明確に指定してください。
• export_blueprint_image による書き込みは、CLOUDCRAFT_EXPORT_DIR （デフォルトではプロセス専用の一時サブディレクトリ）以下にサンドボックス化され、overwrite=True を指定しない限り、既存のファイルへの上書きを拒否します。
• 読み取り中心の構成では、読み取り専用のスコープ（Cloudcraft がスコープ付きキーを追加した場合）を持つ専用の Cloudcraft ユーザーを作成し、そのキーを MCP に使用してください。
• 対応バージョンと非公開の報告手順は SECURITY.md に、データフローは PRIVACY.md に記載されています。

貢献

https://github.com/hypark5540/cloudcraft-mcp で、Issue や PR を歓迎しています。提出前に ruff、mypy、pytest を実行してください。

ライセンス

MIT — LICENSE を参照してください。

関連情報

• Cloudcraft API ドキュメント
• Model Context Protocol 仕様
• awslabs/mcp — AWS の MCP サーバーコレクション
• modelcontextprotocol/servers — MCP サーバーのリファレンス実装