Skip to main content
Glama

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:

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.

export_blueprint_budget

Export a blueprint's cost estimate as CSV / XLSX on disk.

list_teams

List teams linked to the account.

list_aws_accounts

List AWS accounts connected for live-scan snapshots.

snapshot_aws

Live-scan one AWS region into blueprint JSON (optional filter / exclude).

list_azure_accounts

List Azure accounts connected for live-scan snapshots.

snapshot_azure

Live-scan one Azure region into blueprint JSON (optional filter / exclude).

Related MCP server: AWS MCP Server

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.

Channel

Command

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/cloudcraft-mcp@0.1.8

Docker / GHCR

docker run --rm -i -e CLOUDCRAFT_API_KEY ghcr.io/hypark5540/cloudcraft-mcp:0.1.8

Claude Desktop

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

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 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.

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

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).

CLOUDCRAFT_EXPORT_DIR

no

private temp subdirectory

Directory that export_blueprint_image may write under.

CLOUDCRAFT_ENABLE_WRITES

no

false

Permit create_blueprint and update_blueprint.

CLOUDCRAFT_ENABLE_DELETES

no

false

Permit deletes when writes are also enabled.

CLOUDCRAFT_MAX_RESPONSE_BYTES

no

26214400

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

{
  "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
├── 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.

Available Tools

13 tools
create_blueprintB

Create a new Cloudcraft blueprint.

Args: name: Display name for the new blueprint. data: Full blueprint payload (nodes, edges, groups, surfaces, text, icons, connectors, theme, projection, etc.). See README for a minimal example.

Returns the created blueprint metadata including the assigned id.

Inputs: data (required), name (required). Returns: object

delete_blueprintA
Destructive

Delete a Cloudcraft blueprint after exact-id confirmation.

Args: blueprint_id: Blueprint UUID. confirm_blueprint_id: Repeat the exact UUID to acknowledge the irreversible operation.

Inputs: blueprint_id (required), confirm_blueprint_id (required). Returns: object

export_blueprint_budgetA
Destructive

Export a blueprint's cost estimate (budget) to a CSV or XLSX file on disk.

Same write sandbox as :func:export_blueprint_image.

Args: blueprint_id: Blueprint UUID. format: csv or xlsx. Default csv. output_path: Absolute path under the export directory. Default: <export_dir>/cloudcraft_<uuid>_budget.<ext>. currency: ISO 4217 code — USD (default), AUD, CHF, EUR, GBP, HKD, JPY, NOK, NZD, SEK, ZAR. period: h hourly, d daily, w weekly, m monthly (default), y yearly. rate: effective (default, includes upfront fees) or stated. overwrite: Set True to replace an existing file.

Returns: {"path": <saved_path>, "bytes": <size>, "format": <fmt>}

Inputs: blueprint_id (required), rate, format, period, +3 more. Returns: object

export_blueprint_imageA
Destructive

Render a Cloudcraft blueprint to an image file on disk.

Writes are restricted to CLOUDCRAFT_EXPORT_DIR (default: system temp directory). Set CLOUDCRAFT_EXPORT_DIR=/path/to/dir in the MCP server environment to allow saving under a different directory.

Args: blueprint_id: Blueprint UUID. format: One of png, svg, pdf, mxgraph. Default png. output_path: Absolute path to save to, must resolve under the export directory. Default: <export_dir>/cloudcraft_<uuid>.<ext>. scale: Optional PNG render scale (e.g. 1.0, 2.0). PNG only. transparent: PNG transparent background (bool). PNG only. overwrite: Set True to replace an existing file at output_path. Default False — existing files are preserved.

Returns: {"path": <saved_path>, "bytes": <size>, "format": <fmt>}

Inputs: blueprint_id (required), scale, format, overwrite, +2 more. Returns: object

get_blueprintA
Read-only

Fetch the full blueprint payload (nodes, edges, groups, layout).

Args: blueprint_id: Blueprint UUID from :func:list_blueprints.

Inputs: blueprint_id (required). Returns: object

list_aws_accountsA
Read-only

List AWS accounts registered with Cloudcraft for live-scan snapshots.

Inputs: no named parameters. Returns: object

list_azure_accountsA
Read-only

List Azure accounts registered with Cloudcraft for live-scan snapshots.

Inputs: no named parameters. Returns: object

list_blueprintsA
Read-only

List every Cloudcraft blueprint (diagram) in the authenticated account.

Returns a compact summary per blueprint (id, name, tags, updatedAt). Use :func:get_blueprint afterwards to pull the full node / edge JSON.

Inputs: no named parameters. Returns: object

list_teamsB
Read-only

List the teams linked to the Cloudcraft account (id, name, members).

Inputs: no named parameters. Returns: object

snapshot_awsB
Idempotent

Scan one AWS region into a blueprint JSON via Cloudcraft live-scan.

Inputs: region (required), account_id (required), filter, exclude. Returns: object

snapshot_azureC
Idempotent

Scan one Azure region into a blueprint JSON via Cloudcraft live-scan.

Inputs: region (required), account_id (required), filter, exclude. Returns: object

update_blueprintA
DestructiveIdempotent

Replace the full data payload of an existing blueprint.

Args: blueprint_id: Blueprint UUID. data: Full blueprint payload (same shape as :func:create_blueprint).

Inputs: data (required), blueprint_id (required). Returns: object

whoamiA
Read-only

Return the Cloudcraft user profile for the current API key.

Useful as a sanity check after configuring a new key.

Inputs: no named parameters. Returns: object

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 13 tools

    Disambiguation5/5

    Each tool maps to a distinct resource/action pair: team/profile read, blueprint CRUD, two clearly separated export formats (image vs budget), and account listing vs region snapshots. The only near-overlap, export_blueprint_image vs export_blueprint_budget, is made unambiguous by explicit format and output descriptions.

    Naming Consistency4/5

    Almost everything follows a clean verb_noun snake_case pattern (list_*, get_*, create_*, update_*, delete_*, export_*, snapshot_*). The lone deviation is `whoami`, which breaks the pattern but is idiomatic and unambiguous.

    Tool Count5/5

    13 tools is well within the ideal 3-15 range and each earns its place: 5 blueprint CRUD tools, 2 exports, 2 account listers, 2 snapshotters, plus team/profile reads. No filler tools.

    Completeness4/5

    Blueprint lifecycle is fully covered (list/get/create/update/delete plus image and budget export), and both AWS and Azure snapshot paths exist. Minor gaps: no account-level get/registration tools, no team management, and update_blueprint replaces the whole payload so rename/metadata edits are awkward — all workaroundable.

    Maintenance

    ActivityMaintained
    ResponsivenessLimited data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      Enables Claude to interact with core AWS services like S3, EC2, RDS, and CloudWatch, along with a generic SDK wrapper for any AWS operation. It also supports cost monitoring and optional vector store capabilities for document ingestion and search.
      10
      3
      -
    • A
      license
      B
      quality
      D
      maintenance
      Enables Claude Desktop to interact with 57 AWS services using over 200 tools and local machine profiles. It supports multi-profile configurations and features a read-only safe mode by default to manage infrastructure like EC2, S3, and Lambda securely.
      100
      BSD 3-Clause
    • A
      license
      A
      quality
      D
      maintenance
      Enables browsing S3 buckets and objects, and generating secure presigned URLs for downloads and uploads, through natural language commands in MCP clients like Claude Desktop.
      3
      4
      MIT