cloudcraft-mcp

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

Features

Nine tools exposed to the MCP host:

Tool	Description
whoami	Return the Cloudcraft user profile for the configured key.
list_blueprints	List every blueprint in the account.
get_blueprint	Fetch a blueprint's full node / edge JSON.
create_blueprint	Create a new blueprint from a JSON payload.
update_blueprint	Replace an existing blueprint's payload.
delete_blueprint	Delete a blueprint (irreversible).
export_blueprint_image	Render a blueprint to PNG / SVG / PDF / mxgraph on disk.
list_aws_accounts	List AWS accounts connected for live-scan snapshots.
snapshot_aws	Take a live-scan snapshot of one AWS service.

Requirements

• Python 3.10+
• uv (brew install uv)
• Cloudcraft API key — generate one at https://app.cloudcraft.co/ → User settings → API keys

Install

Clone the repo and let uv resolve dependencies on first run — no explicit install step required.

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

Claude Desktop integration

Edit ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or the equivalent on your platform:

{
  "mcpServers": {
    "cloudcraft": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/cloudcraft-mcp",
        "run",
        "cloudcraft-mcp"
      ],
      "env": {
        "CLOUDCRAFT_API_KEY": "your-key-here"
      }
    }
  }
}

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

Environment variables

Name	Required	Default	Purpose
CLOUDCRAFT_API_KEY	yes	—	API key (Bearer). Generated in Cloudcraft User settings.
CLOUDCRAFT_BASE_URL	no	https://api.cloudcraft.co	Override for proxies or future API versions.
CLOUDCRAFT_LOG_LEVEL	no	WARNING	Stderr log verbosity (DEBUG / INFO / WARNING / ERROR).

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 the EC2 instances in ap-northeast-2 for my connected AWS account."

Blueprint payload shape

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

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

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

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

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
├── 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.
• 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.
• delete_blueprint is irreversible — when asking Claude to delete, be explicit about the target id.
• 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.

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

• Cloudcraft API documentation
• Model Context Protocol specification
• awslabs/mcp — AWS's collection of MCP servers
• modelcontextprotocol/servers — reference MCP server implementations