cloudcraft-mcp
An unofficial MCP server that lets Claude Desktop and other MCP clients read, create, update, delete, export, and live-scan Cloudcraft cloud architecture blueprints via the Cloudcraft API.
Account info:
whoamireturns the Cloudcraft user profile for the configured API key (a sanity check after setup).Blueprints — read:
list_blueprintslists every blueprint as a compact summary (id, name, tags, updatedAt);get_blueprintfetches a blueprint's full node/edge/group/layout JSON.Blueprints — write (requires
CLOUDCRAFT_ENABLE_WRITES=true):create_blueprintcreates a blueprint from a typed payload (nodes, edges, groups, surfaces, text, icons, connectors, theme, projection, live options);update_blueprintreplaces an existing blueprint's payload.Blueprints — delete (requires writes plus
CLOUDCRAFT_ENABLE_DELETES=trueand an exact repeated ID):delete_blueprint, which is irreversible.Export:
export_blueprint_imagerenders a blueprint to PNG/SVG/PDF/mxgraph on disk (optional PNG scale/transparency), sandboxed underCLOUDCRAFT_EXPORT_DIR; the README also documentsexport_blueprint_budgetfor CSV/XLSX cost estimates.Live-scan inventory:
list_aws_accountsandsnapshot_aws(account id, region, service) capture AWS infrastructure into blueprint JSON; the README additionally listslist_teams,list_azure_accounts, andsnapshot_azurewith optionalfilter/exclude.Safety defaults: read-only by default, API key supplied via
CLOUDCRAFT_API_KEY(never in args), configurable base URL, log level, and max response size, with tool annotations distinguishing read-only from mutating/destructive tools.
Note: the README advertises thirteen tools, but this schema exposes eleven — export_blueprint_budget, list_teams, and list_azure_accounts are absent, while snapshot_azure is missing in favor of the AWS-only snapshot_aws.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@cloudcraft-mcp List my Cloudcraft blueprints"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
cloudcraft-mcp
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 |
| Return the Cloudcraft user profile for the configured key. |
| List every blueprint in the account. |
| Fetch a blueprint's full node / edge JSON. |
| Create a new blueprint from a JSON payload. |
| Replace an existing blueprint's payload. |
| Delete a blueprint (irreversible). |
| Render a blueprint to PNG / SVG / PDF / mxgraph on disk. |
| Export a blueprint's cost estimate as CSV / XLSX on disk. |
| List teams linked to the account. |
| List AWS accounts connected for live-scan snapshots. |
| Live-scan one AWS region into blueprint JSON (optional |
| List Azure accounts connected for live-scan snapshots. |
| Live-scan one Azure region into blueprint JSON (optional |
Related MCP server: AWS MCP Server
Requirements
uv for the recommended
uvxand npm launchersNode.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 |
|
pipx |
|
npm / npx |
|
Docker / GHCR |
|
Claude Desktop | Download |
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 exitClaude 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 |
| yes | — | API key (Bearer). Generated in Cloudcraft User settings. |
| no |
| Override for proxies or future API versions. |
| no |
| Stderr log verbosity ( |
| no | private temp subdirectory | Directory that |
| no |
| Permit |
| no |
| Permit deletes when writes are also enabled. |
| no |
| 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-2of 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 checkTests 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=xmlProject 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.mdDesign notes
Transport / logic split.
client.pyis a plain async HTTP client you can import from scripts or CLI tools without pulling the MCP runtime.server.pyonly owns the MCP tool surface.Bearer-token auth. Cloudcraft's API expects
Authorization: Bearer <key>(notApikey). 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
CloudcraftErrorwith status and body preserved, re-wrapped asRuntimeErrorat 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=trueonly for clients that need create/update access. Deletes additionally requireCLOUDCRAFT_ENABLE_DELETES=trueand an exact repeated blueprint ID on every call.delete_blueprintis irreversible — when asking Claude to delete, be explicit about the target id.export_blueprint_imagewrites are sandboxed underCLOUDCRAFT_EXPORT_DIR(a process-private temporary subdirectory by default) and refuse to overwrite existing files unlessoverwrite=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
awslabs/mcp — AWS's collection of MCP servers
modelcontextprotocol/servers — reference MCP server implementations
Available Tools
13 toolscreate_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_blueprintADestructive
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_budgetADestructive
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_imageADestructive
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_blueprintARead-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_accountsARead-only
List AWS accounts registered with Cloudcraft for live-scan snapshots.
Inputs: no named parameters. Returns: object
list_azure_accountsARead-only
List Azure accounts registered with Cloudcraft for live-scan snapshots.
Inputs: no named parameters. Returns: object
list_blueprintsARead-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_teamsBRead-only
List the teams linked to the Cloudcraft account (id, name, members).
Inputs: no named parameters. Returns: object
snapshot_awsBIdempotent
Scan one AWS region into a blueprint JSON via Cloudcraft live-scan.
Inputs: region (required), account_id (required), filter, exclude. Returns: object
snapshot_azureCIdempotent
Scan one Azure region into a blueprint JSON via Cloudcraft live-scan.
Inputs: region (required), account_id (required), filter, exclude. Returns: object
update_blueprintADestructiveIdempotent
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
whoamiARead-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
Scored across 13 tools
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.
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.
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.
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
Related MCP Connectors
AI Visibility and Content Intelligence tools for Claude and MCP-compatible agents.
Connect Amazon Seller Central to Claude or ChatGPT via MCP. Orders, inventory, pricing, fees, FBA.
Hosted Amazon Seller Central and Amazon Ads MCP server for Claude, ChatGPT, Cursor, and agents.
Hosted Amazon Seller and Vendor MCP server for Claude, ChatGPT, Cursor, Codex, Gemini, Copilot.
Related MCP Servers
- AlicenseBqualityDmaintenanceEnables 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.103-
- AlicenseBqualityDmaintenanceEnables 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.100BSD 3-Clause
- AlicenseAqualityDmaintenanceEnables browsing S3 buckets and objects, and generating secure presigned URLs for downloads and uploads, through natural language commands in MCP clients like Claude Desktop.34MIT
- AlicenseNot gradedqualityDmaintenanceEnables natural language control of AWS resources (EC2, Security Groups, S3, Bedrock, etc.) directly from Claude Desktop or Claude Code.75 PyPIMIT