Cloudcraft MCP
Unofficial MCP server for reading and managing Cloudcraft architecture blueprints
Open source Open in the app JSON README (API)
About
Unofficial MCP server for reading and managing Cloudcraft architecture blueprints
Details
- Kind
- MCP servers
- Topic
- No topic detected
- Publisher
- hypark5540
- Origin
- official
- Category
- ferramentas
- Transport
- local
- Version
- 0.1.6
- Open pull requests
- 4
- Last push
- 2026-09-06T18:36:13Z
- Repository state
- ativo
- Language
- Python
- License
- MIT
- Added
- 2026-08-29 04:00:08
- Updated
- 2026-08-29 04:00:08
- Origin id
io.github.hypark5540/cloudcraft-mcp
README
<!-- mcp-name: io.github.hypark5540/cloudcraft-mcp -->
# cloudcraft-mcp
[](https://github.com/hypark5540/cloudcraft-mcp/actions/workflows/ci.yml)
[](https://codecov.io/gh/hypark5540/cloudcraft-mcp)
[](https://pypi.org/project/cloudcraft-mcp/)
[](https://www.npmjs.com/package/@hypark5540/cloudcraft-mcp)
[](LICENSE)
[](https://www.python.org/downloads/)
Unofficial Model Context Protocol (MCP) server for
[Cloudcraft](https://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
- [uv](https://docs.astral.sh/uv/getting-started/installation/) 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.6 cloudcraft-mcp` |
| pipx | `pipx run --spec cloudcraft-mcp==0.1.6 cloudcraft-mcp` |
| npm / npx | `npx -y @hypark5540/cloudcraft-mcp@0.1.6` |
| Docker / GHCR | `docker run --rm -i -e CLOUDCRAFT_API_KEY ghcr.io/hypark5540/cloudcraft-mcp:0.1.6` |
| 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:
```bash
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](https://docs.astral.sh/uv/getting-started/installation/), 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.6",
"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](docs/clients.md) 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 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:
```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](https://developers.cloudcraft.co/) for the full node-type catalog and service-specific fields.
## Development
```bash
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](https://lundberg.github.io/respx/) so no API key is required.
#### Coverage
CI uploads `coverage.xml` from the Python 3.12 matrix cell to
[Codecov](https://codecov.io/gh/hypark5540/cloudcraft-mcp). 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](SECURITY.md); data flow is documented in [PRIVACY.md](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](LICENSE).
## Related
- [Cloudcraft API documentation](https://developers.cloudcraft.co/)
- [Model Context Protocol specification](https://modelcontextprotocol.io/)
- [awslabs/mcp](https://github.com/awslabs/mcp) — AWS's collection of MCP servers
- [modelcontextprotocol/servers](https://github.com/modelcontextprotocol/servers) — reference MCP server implementations