Cloudcraft MCP

io.github.hypark5540Published by GitHub account hypark5540v0.1.8Updated Oct 26, 2026

Unofficial MCP server for reading and managing Cloudcraft architecture blueprints

VerifiedSTDIODesktop onlyCloud & InfrastructureMedia & Design

Overview

AI-generated overview

Unofficial MCP server for Cloudcraft that lets an assistant list, read, export, create, update and delete cloud architecture blueprints.

What you can do
  • Check the Cloudcraft user profile behind the configured key
  • List, read and inspect blueprints, teams, and connected AWS and Azure accounts
  • Create, replace or delete blueprints from full JSON payloads
  • Export blueprints as PNG, SVG, PDF or mxgraph images, and cost estimates as CSV or XLSX
  • Live-scan one AWS or Azure region into blueprint JSON, with optional filter and exclude
When to use it
Useful when you keep cloud architecture diagrams in Cloudcraft and want an assistant to summarize existing blueprints, export diagrams or budget estimates, generate new blueprints from a design, or snapshot a connected cloud account region.
Requirements
Runs locally over stdio via uvx, pipx, npx, Docker or a Claude Desktop bundle; the npm launcher needs Node.js 22+ and uv. Requires a Cloudcraft API key in CLOUDCRAFT_API_KEY and network access to the Cloudcraft API; optional variables set the base URL, export directory, log level, response size limit, and write/delete gates.
Before you install
The Cloudcraft API key grants full read and write over the account, so treat it as a secret and rotate it. Writes are off by default and deletes need both CLOUDCRAFT_ENABLE_WRITES and CLOUDCRAFT_ENABLE_DELETES plus an exact repeated blueprint ID; deletion is irreversible. Tool annotations are only hints, so keep host approval prompts on. Exports write files under CLOUDCRAFT_EXPORT_DIR.

Installation

In SourceWeft

  1. Open Cloudcraft MCP in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

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

Source: README.md at commit 25ba3ab

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

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

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts