build123d-mcp

build123d CAD 작업을 도구로 노출하여 AI 어시스턴트가 3D 형상을 대화형으로 구축, 검사 및 반복할 수 있게 해주는 MCP(Model Context Protocol) 서버입니다.

목적

AI를 사용하여 build123d 스크립트를 작성할 때, AI는 자신이 생성하는 형상을 볼 수 없는 '눈먼' 상태로 작업하게 됩니다. 이 서버는 피드백 루프를 닫아줍니다. AI는 전체 스크립트를 작성하고 올바르기를 바라는 대신, 형상을 생성하고, 뷰를 렌더링하고, 치수를 쿼리하고, 오류를 점진적으로 포착할 수 있습니다.

Related MCP server: 3D MCP Server

도구

• execute — 지속적인 세션에서 build123d Python 코드를 실행합니다. show(shape, name)을 사용하여 명명된 파트를 등록하세요.

• render_view — 하나 이상의 형상을 PNG 또는 SVG로 렌더링합니다. 어셈블리 합성, 고품질 테셀레이션 및 단면 클립 평면을 지원합니다.

• measure — 바운딩 박스, 부피, 표면적, 토폴로지, 최소 벽 두께 또는 두 명명된 본체 사이의 간격을 쿼리합니다.

• export — 한 번의 호출로 STEP, STL 또는 둘 다로 내보냅니다. 명명된 객체 또는 현재 형상을 대상으로 합니다.

• session_state — 활성 형상, 명명된 객체 및 스냅샷 이름의 전체 JSON 스냅샷입니다.

• health_check — 작업을 시작하기 전에 VTK/SVG/STEP/STL 종속성이 제대로 작동하는지 확인합니다.

• save_snapshot / restore_snapshot / diff_snapshot — 기하학적 상태를 체크포인트하고, 복구하고, 비교합니다.

• interference — 두 명명된 형상 사이의 교차 부피를 확인합니다.

• list_objects — 형상 통계와 함께 모든 명명된 형상을 나열합니다.

• version — 서버 버전을 반환합니다.

• reset — 세션을 빈 상태로 초기화합니다.

전체 도구 참조 및 사용 패턴은 llms.md를 참조하세요.

요구 사항

• uv

• MCP 호환 클라이언트 (Claude Code, Claude Desktop, Cursor 등)

모든 Python 종속성(build123d, vtk 등)은 uv에 의해 자동으로 설치됩니다.

설치

복제할 필요가 없습니다. PyPI에서 직접 설치하세요:

pip install build123d-mcp

또는 uv tool run을 사용하세요. 사전 설치 없이 한 단계로 패키지를 가져와 실행합니다(아래 참조).

MCP 클라이언트에 추가

서버는 stdio를 통해 실행되며, 클라이언트는 uv tool run build123d-mcp를 사용하여 하위 프로세스로 실행합니다.

Python 버전에 대한 참고 사항. 아래의 모든 예제는 --python 3.12를 전달합니다. VTK와 cadquery-ocp는 아직 Python 3.13+용 휠을 제공하지 않으므로 3.12로 고정해야 합니다. 이미 Python 3.12가 없는 경우 uv가 관리형 Python 3.12를 자동으로 다운로드합니다.

Claude Code

프로젝트의 .mcp.json(또는 전역 사용 시 ~/.claude/mcp.json)에 추가하세요:

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

편집 후 Claude Code를 다시 시작하세요. 연결되면 도구가 자동으로 나타납니다.

Claude Desktop

~/Library/Application Support/Claude/claude_desktop_config.json(macOS) 또는 %APPDATA%\Claude\claude_desktop_config.json(Windows)을 편집하세요:

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

저장 후 Claude Desktop을 다시 시작하세요.

Cursor

Settings → MCP를 열고 새 서버 항목을 추가하거나 ~/.cursor/mcp.json을 편집하세요:

{
  "mcpServers": {
    "build123d-mcp": {
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

VS Code (GitHub Copilot / Continue)

Continue 확장의 경우 .continue/config.json에 추가하세요:

{
  "mcpServers": [
    {
      "name": "build123d-mcp",
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  ]
}

MCP를 지원하는 GitHub Copilot의 경우 작업 공간의 .vscode/mcp.json에 추가하세요:

{
  "servers": {
    "build123d-mcp": {
      "type": "stdio",
      "command": "uv",
      "args": ["tool", "run", "--python", "3.12", "build123d-mcp"]
    }
  }
}

시스템 프롬프트

최상의 결과를 얻으려면 default_prompt.md의 내용을 AI 클라이언트의 시스템 프롬프트로 붙여넣으세요. 이는 어시스턴트에게 점진적으로 작업하고, 각 단계 후에 형상을 확인하며, 올바른 순서로 도구를 사용하도록 지시합니다.

상태

활성 개발 중 (v0.1.0).