Skip to main content
Glama

cloudcraft-mcp

CI License: MIT Python 3.10+

Cloudcraft.co를 위한 Model Context Protocol (MCP) 서버 — Claude Desktop 및 기타 MCP 클라이언트에서 클라우드 아키텍처 청사진을 나열, 읽기, 내보내기 및 구축할 수 있습니다.

기능

MCP 호스트에 노출되는 9가지 도구:

도구

설명

whoami

구성된 키에 대한 Cloudcraft 사용자 프로필을 반환합니다.

list_blueprints

계정의 모든 청사진을 나열합니다.

get_blueprint

청사진의 전체 노드 / 엣지 JSON을 가져옵니다.

create_blueprint

JSON 페이로드에서 새 청사진을 생성합니다.

update_blueprint

기존 청사진의 페이로드를 교체합니다.

delete_blueprint

청사진을 삭제합니다 (복구 불가).

export_blueprint_image

청사진을 디스크에 PNG / SVG / PDF / mxgraph로 렌더링합니다.

list_aws_accounts

라이브 스캔 스냅샷을 위해 연결된 AWS 계정을 나열합니다.

snapshot_aws

하나의 AWS 서비스에 대한 라이브 스캔 스냅샷을 찍습니다.

Related MCP server: AWS MCP Server

요구 사항

설치

저장소를 복제하고 첫 실행 시 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 exit

Claude 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가 연결된 것으로 표시되어야 합니다.

환경 변수

이름

필수

기본값

목적

CLOUDCRAFT_API_KEY

예

—

API 키 (Bearer). Cloudcraft 사용자 설정에서 생성.

CLOUDCRAFT_BASE_URL

아니요

https://api.cloudcraft.co

프록시 또는 향후 API 버전을 위한 재정의.

CLOUDCRAFT_LOG_LEVEL

아니요

WARNING

Stderr 로그 상세 수준 (DEBUG / INFO / WARNING / ERROR).

사용 예시 (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를 참조하세요.

관련 항목

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