cloudcraft-mcp
cloudcraft-mcp
Cloudcraft.co를 위한 Model Context Protocol (MCP) 서버 — Claude Desktop 및 기타 MCP 클라이언트에서 클라우드 아키텍처 청사진을 나열, 읽기, 내보내기 및 구축할 수 있습니다.
기능
MCP 호스트에 노출되는 9가지 도구:
도구 | 설명 |
| 구성된 키에 대한 Cloudcraft 사용자 프로필을 반환합니다. |
| 계정의 모든 청사진을 나열합니다. |
| 청사진의 전체 노드 / 엣지 JSON을 가져옵니다. |
| JSON 페이로드에서 새 청사진을 생성합니다. |
| 기존 청사진의 페이로드를 교체합니다. |
| 청사진을 삭제합니다 (복구 불가). |
| 청사진을 디스크에 PNG / SVG / PDF / mxgraph로 렌더링합니다. |
| 라이브 스캔 스냅샷을 위해 연결된 AWS 계정을 나열합니다. |
| 하나의 AWS 서비스에 대한 라이브 스캔 스냅샷을 찍습니다. |
Related MCP server: AWS MCP Server
요구 사항
Python 3.10+
uv (
brew install uv)Cloudcraft API 키 — https://app.cloudcraft.co/ → 사용자 설정 → API 키에서 생성
설치
저장소를 복제하고 첫 실행 시 uv가 종속성을 해결하도록 하세요 — 별도의 명시적인 설치 단계는 필요하지 않습니다.
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 exitClaude Desktop 통합
~/Library/Application Support/Claude/claude_desktop_config.json (macOS) 또는 사용 중인 플랫폼의 해당 파일을 편집하세요:
{
"mcpServers": {
"cloudcraft": {
"command": "uv",
"args": [
"--directory",
"/absolute/path/to/cloudcraft-mcp",
"run",
"cloudcraft-mcp"
],
"env": {
"CLOUDCRAFT_API_KEY": "your-key-here"
}
}
}
}Claude Desktop을 다시 시작하세요. 개발자 탭에 cloudcraft가 연결된 것으로 표시되어야 합니다.
환경 변수
이름 | 필수 | 기본값 | 목적 |
| 예 | — | API 키 (Bearer). Cloudcraft 사용자 설정에서 생성. |
| 아니요 |
| 프록시 또는 향후 API 버전을 위한 재정의. |
| 아니요 |
| Stderr 로그 상세 수준 ( |
사용 예시 (Claude에서)
서버가 연결되면 Claude에게 다음과 같이 질문하세요:
"내 Cloudcraft 청사진을 나열하고 각각이 무엇을 나타내는지 요약해 줘."
"청사진
f0086b32-...를 PNG로 내보내서 내 바탕 화면에 저장해 줘."
"내가 방금 설계한 아키텍처를 가져와서 'Prod 2026'이라는 새 Cloudcraft 청사진을 만들어 줘."
"내 연결된 AWS 계정의
ap-northeast-2에 있는 EC2 인스턴스 스냅샷을 찍어 줘."
청사진 페이로드 형태
create_blueprint / update_blueprint는 전체 Cloudcraft data 객체를 허용합니다. 최소 페이로드:
{
"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
}전체 노드 유형 카탈로그 및 서비스별 필드는 Cloudcraft API 문서를 참조하세요.
개발
uv sync --extra dev
uv run pytest # unit tests (no network)
uv run ruff check . # lint
uv run mypy src # type check테스트는 respx를 사용하여 HTTP 계층을 모의하므로 API 키가 필요하지 않습니다.
프로젝트 레이아웃
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설계 참고 사항
전송 / 로직 분리.
client.py는 MCP 런타임을 가져오지 않고도 스크립트나 CLI 도구에서 가져올 수 있는 일반 비동기 HTTP 클라이언트입니다.server.py는 MCP 도구 인터페이스만 담당합니다.Bearer 토큰 인증. Cloudcraft의 API는
Authorization: Bearer <key>(Apikey 아님)를 기대합니다. 클라이언트가 이를 자동으로 설정합니다.프로세스 인수에 비밀 정보 없음. API 키는
CLOUDCRAFT_API_KEY에서 읽어오며, 명령줄에서 절대 전달하지 마세요.오류 표면. 2xx가 아닌 응답은 상태와 본문이 보존된
CloudcraftError를 발생시키며, Claude가 읽을 수 있는 메시지를 볼 수 있도록 MCP 경계에서RuntimeError로 다시 래핑됩니다.
보안
API 키는 Cloudcraft 계정에 대한 전체 읽기/쓰기 권한을 부여합니다. 비밀로 취급하고 정기적으로 교체하세요.
delete_blueprint는 복구할 수 없습니다. Claude에게 삭제를 요청할 때는 대상 ID를 명확히 하세요.읽기 위주의 설정인 경우, 전용 Cloudcraft 사용자를 생성하여 읽기 전용 범위를 지정하고(Cloudcraft가 범위 지정 키를 추가하는 경우) 해당 키를 MCP에 사용하세요.
기여
이슈와 PR은 https://github.com/hypark5540/cloudcraft-mcp에서 환영합니다. 제출하기 전에 ruff, mypy, pytest를 실행해 주세요.
라이선스
MIT — LICENSE를 참조하세요.
관련 항목
awslabs/mcp — AWS의 MCP 서버 모음
modelcontextprotocol/servers — 참조 MCP 서버 구현
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