Cloudcraft MCP

io.github.hypark5540由 GitHub 账号 hypark5540 发布v0.1.8更新于 Oct 26, 2026

Unofficial MCP server for reading and managing Cloudcraft architecture blueprints

概览

AI 生成的概览

Cloudcraft 的非官方 MCP 服务器,让助手列出、读取、导出、创建、更新和删除云架构蓝图。

可以做什么
  • 查看当前密钥对应的 Cloudcraft 用户资料
  • 列出、读取和查看蓝图、团队以及已连接的 AWS 与 Azure 账户
  • 用完整 JSON 载荷创建、替换或删除蓝图
  • 将蓝图导出为 PNG、SVG、PDF 或 mxgraph 图片,将成本估算导出为 CSV 或 XLSX
  • 实时扫描某个 AWS 或 Azure 区域并生成蓝图 JSON,可选过滤与排除
适用场景
适合在 Cloudcraft 中维护云架构图的场景:让助手总结现有蓝图、导出架构图或预算估算、根据设计生成新蓝图,或对已连接的云账户区域做快照。
运行要求
通过 uvx、pipx、npx、Docker 或 Claude Desktop 安装包在本地以 stdio 运行;npm 启动方式需要 Node.js 22+ 和 uv。需要 Cloudcraft API 密钥(环境变量 CLOUDCRAFT_API_KEY)以及访问 Cloudcraft API 的网络;可选变量可设置基础 URL、导出目录、日志级别、响应大小上限和写入/删除开关。
安装前请注意
Cloudcraft API 密钥拥有账户的完整读写权限,应视为机密并定期轮换。写入默认关闭,删除还需同时开启 CLOUDCRAFT_ENABLE_WRITES 与 CLOUDCRAFT_ENABLE_DELETES 并在每次调用中重复精确的蓝图 ID;删除不可恢复。工具注解只是提示,请保持宿主端的工具审批开启。导出文件写入 CLOUDCRAFT_EXPORT_DIR 指定的目录。

安装

在 SourceWeft 中

  1. 打开 控制台中的 Cloudcraft MCP,将其添加到工作区。
  2. 为需要使用其工具的对话启用该服务。

Desktop only,通过 STDIO。 STDIO 服务会启动本地进程,因此需要 SourceWeft 桌面宿主。

其他 MCP 客户端

参照 仓库 中的启动说明。

README

cloudcraft-mcp

[CI] [codecov] [PyPI] [npm] [License: MIT] [Python 3.10+]

Unofficial Model Context Protocol (MCP) server for Cloudcraft — list, read, export, and build cloud architecture blueprints from Claude Desktop and other MCP clients.

Features

Thirteen tools exposed to the MCP host:

ToolDescription
whoamiReturn the Cloudcraft user profile for the configured key.
list_blueprintsList every blueprint in the account.
get_blueprintFetch a blueprint's full node / edge JSON.
create_blueprintCreate a new blueprint from a JSON payload.
update_blueprintReplace an existing blueprint's payload.
delete_blueprintDelete a blueprint (irreversible).
export_blueprint_imageRender a blueprint to PNG / SVG / PDF / mxgraph on disk.
export_blueprint_budgetExport a blueprint's cost estimate as CSV / XLSX on disk.
list_teamsList teams linked to the account.
list_aws_accountsList AWS accounts connected for live-scan snapshots.
snapshot_awsLive-scan one AWS region into blueprint JSON (optional filter / exclude).
list_azure_accountsList Azure accounts connected for live-scan snapshots.
snapshot_azureLive-scan one Azure region into blueprint JSON (optional filter / exclude).

Requirements

  • uv for the recommended uvx and npm launchers
  • Node.js 22+ only when using the npm launcher
  • Cloudcraft API key — generate one at https://app.cloudcraft.co/ → User settings → API keys

Install

Use an immutable version in client configuration so upgrades are deliberate.

ChannelCommand
PyPI / uvxuvx --from cloudcraft-mcp==0.1.8 cloudcraft-mcp
pipxpipx run --spec cloudcraft-mcp==0.1.8 cloudcraft-mcp
npm / npxnpx -y @hypark5540/[email protected]
Docker / GHCRdocker run --rm -i -e CLOUDCRAFT_API_KEY ghcr.io/hypark5540/cloudcraft-mcp:0.1.8
Claude DesktopDownload cloudcraft-mcp.mcpb from the matching GitHub release

uvx is delivered by the PyPI package; there is no separate uvx registry. The npm package embeds the byte-identical Python wheel and invokes it through uv, so the npm path requires both Node.js and uv. It does not download code in a postinstall hook.

For development from a checkout:

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

Claude Desktop integration

Install uv, then add this entry to Claude Desktop's configuration. Prefer Claude's secret storage when available; the literal below is only a portable example.

json
{  "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"      }    }  }}

Restart Claude Desktop. The Developer tab should show cloudcraft as connected.

See client setup for Cursor, Gemini CLI, npm, Docker, and MCPB examples.

Environment variables

NameRequiredDefaultPurpose
CLOUDCRAFT_API_KEYyes—API key (Bearer). Generated in Cloudcraft User settings.
CLOUDCRAFT_BASE_URLnohttps://api.cloudcraft.coOverride for proxies or future API versions.
CLOUDCRAFT_LOG_LEVELnoWARNINGStderr log verbosity (DEBUG / INFO / WARNING / ERROR).
CLOUDCRAFT_EXPORT_DIRnoprivate temp subdirectoryDirectory that export_blueprint_image may write under.
CLOUDCRAFT_ENABLE_WRITESnofalsePermit create_blueprint and update_blueprint.
CLOUDCRAFT_ENABLE_DELETESnofalsePermit deletes when writes are also enabled.
CLOUDCRAFT_MAX_RESPONSE_BYTESno26214400Reject oversized Cloudcraft responses before they exhaust memory or disk.

Usage examples (in Claude)

Once the server is connected, ask Claude things like:

"List my Cloudcraft blueprints and summarize what each represents."

"Export blueprint f0086b32-... as PNG and save it to my Desktop."

"Take the architecture I just designed and create a new Cloudcraft blueprint called 'Prod 2026'."

"Snapshot ap-northeast-2 of my connected AWS account, excluding security groups."

"Export the monthly budget of blueprint f0086b32-... as CSV in EUR."

Blueprint payload shape

create_blueprint / update_blueprint accept the full Cloudcraft data object. A minimal payload:

json
{  "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}

Refer to Cloudcraft's API docs for the full node-type catalog and service-specific fields.

Development

bash
uv sync --extra devuv run pytest            # unit tests (no network)uv run ruff check .      # lintuv run mypy src          # type check

Tests mock the HTTP layer with respx so no API key is required.

Coverage

CI uploads coverage.xml from the Python 3.12 matrix cell to Codecov. The project gate is 80% or higher — a PR that drops overall or patch coverage by more than 1 percentage point below that line fails the Codecov check (codecov.yml).

Run the same report locally:

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

Project layout

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

Design notes

  • Transport / logic split. client.py is a plain async HTTP client you can import from scripts or CLI tools without pulling the MCP runtime. server.py only owns the MCP tool surface.
  • Bearer-token auth. Cloudcraft's API expects Authorization: Bearer <key> (not Apikey). The client sets this automatically.
  • No secrets in process args. The API key is read from CLOUDCRAFT_API_KEY; never pass it on the command line.
  • One implementation. PyPI, npm, MCPB, and the container all launch the same versioned Python package rather than maintaining language-specific forks.
  • Error surface. Non-2xx responses raise CloudcraftError with status and body preserved, re-wrapped as RuntimeError at the MCP boundary so Claude sees a readable message.

Security

  • API keys grant full read / write over your Cloudcraft account. Treat them as secrets and rotate regularly.
  • MCP tool annotations mark read-only tools and mutating/destructive tools so compatible hosts can present better approval prompts. These annotations are hints, not an enforcement layer.
  • Environment gates and exact-ID delete confirmation are defense in depth, not an interactive approval workflow; keep the MCP host's tool approval UX enabled.
  • Cloudcraft mutations are disabled by default. Set CLOUDCRAFT_ENABLE_WRITES=true only for clients that need create/update access. Deletes additionally require CLOUDCRAFT_ENABLE_DELETES=true and an exact repeated blueprint ID on every call.
  • delete_blueprint is irreversible — when asking Claude to delete, be explicit about the target id.
  • export_blueprint_image writes are sandboxed under CLOUDCRAFT_EXPORT_DIR (a process-private temporary subdirectory by default) and refuse to overwrite existing files unless overwrite=True.
  • For read-heavy setups, create a dedicated Cloudcraft user with read-only scope (if/when Cloudcraft adds scoped keys) and use that key for MCP.
  • Supported versions and private reporting instructions are in SECURITY.md; data flow is documented in PRIVACY.md.

Contributing

Issues and PRs welcome at https://github.com/hypark5540/cloudcraft-mcp. Please run ruff, mypy, and pytest before submitting.

License

MIT — see LICENSE.

Related

来源:README.md,提交 25ba3ab

工具

0
SourceWeft 尚未在沙箱中启动过该软件包,因此其工具未知。

版本历史

3
  1. v0.1.8最新Oct 20, 2026
  2. v0.1.7Oct 8, 2026
  3. v0.1.6Sep 16, 2026

评分

已满足适用检查项的 50%

该评分衡量此收录条目的完整程度,依据注册中心条目、端点与公开来源计算得出。它不是对服务器本身的评价,也不表示服务器安全或当前可用:可连通性是带日期的检查结果,评分也不包含安装量或用户评价。

  • 近 30 天内可连通25 分

    请保持端点能够响应 MCP 握手;SourceWeft 每 30 天探测一次。

  • 已声明认证方式10 分

    请在注册中心条目中声明凭据请求头,或保持端点能够响应探测,以便判定其认证方式。

  • 已列出工具15 分

    请让服务器在无凭据时响应 tools/list,或发布可在沙箱中无凭据启动的软件包。

  • 描述必需15 分
  • 图标10 分
  • 文档15 分
  • 许可证10 分