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:

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

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.

#### 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:

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
├── 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.
• 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.
• The server does not implement its own approval workflow for create_blueprint, update_blueprint, or delete_blueprint; those calls rely on the MCP host's tool approval UX and the permissions on CLOUDCRAFT_API_KEY.
• 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 (system temp dir 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.

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