PhysBox: MCP

PhysBox: MCP는 LLM 및 MCP 클라이언트(예: Claude Code 또는 Claude Desktop)가 브라우저에서 네 가지 시뮬레이션 웹 애플리케이션과 프로그래밍 방식으로 상호 작용할 수 있도록 하는 MCP(Model Context Protocol) 서버입니다.

모든 통신은 브라우저의 웹 앱에 직접 WebSocket을 통해 JSON으로 처리됩니다. 브라우저 자동화나 DOM 스크래핑이 필요하지 않습니다.

🧠 유일한 AI 네이티브 물리 세계 모델

정적 코드 생성이나 오프라인 파일 출력과 달리, PhysBox는 AI 에이전트에게 상호 작용 가능한 실측 세계 모델을 제공합니다. LLM은 81개의 유형화된 도구 호출을 실행하여 공간 운동학, 회로 노드 파형 및 G-코드 안전 경고를 관찰하고, 반복적으로 설계를 자가 수정할 수 있습니다.

💬 Claude Code 및 Cursor용 예시 에이전트 프롬프트

다음 프롬프트 중 하나를 MCP에 연결된 에이전트에 직접 붙여넣으세요.

• Volt (전자공학):

  "활성 Volt 회로도에서 RC 필터 값을 최적화하여 1kHz 차단 주파수를 달성한 다음, circuit_run_sim을 실행하고 크기 응답을 플로팅하세요."

• Mesh (3D 물리 및 CAD):

  "Mesh에서 4mm 나사 구멍이 있는 OpenSCAD 파라메트릭 마운팅 브래킷을 작성하고, physics_check_collisions를 사용하여 MuJoCo 충돌 안정성 검사를 실행한 후 Z-up STL로 내보내세요."

• Etch (CNC 및 레이저):

  "이 벡터 SVG 로고를 가져와서 합판에 2패스 3mm 스텝다운 이송을 적용하고, 엔드밀 안전 경고를 확인한 후 GRBL G-코드를 생성하세요."

Related MCP server: Tesseron

작동 방식

PhysBox: MCP는 포트 3142에서 WebSocket 릴레이를 설정하는 로컬 컴패니언 서버로 작동합니다.

시뮬레이션 웹 앱 중 하나를 열면 앱이 이 WebSocket 릴레이에 직접 연결됩니다. MCP 클라이언트가 도구 호출을 실행하면 명령이 클라이언트에서 컴패니언 서버로 흐르고, 활성 브라우저 탭으로 전달된 후 결과가 다시 반환됩니다.

MCP Client (e.g. Claude Desktop)
  └── spawns → physbox-mcp (stdio)
                 └── WebSocket Server (ws://localhost:3142)
                                ├── Flux
                                ├── Volt
                                ├── Mesh
                                └── Etch

설치

PyPI에서 직접 컴패니언 서버를 설치하세요.

pip install physbox-mcp

사용법 및 설정

1. 웹 애플리케이션 열기

웹 브라우저에서 시뮬레이션 웹 애플리케이션을 실행하거나 접속하세요.

• Flux: flux.physbox.io

• Volt: volt.physbox.io

• Mesh: mesh.physbox.io

• Etch: etch.physbox.io

페이지 로딩이 완료되는 즉시 컴패니언 WebSocket 서버에 자동으로 등록됩니다.

2. MCP 클라이언트 구성

Claude Desktop의 경우

Claude Desktop 구성 파일(일반적으로 Windows의 경우 AppData/Roaming/Claude/claude_desktop_config.json, macOS의 경우 ~/Library/Application Support/Claude/claude_desktop_config.json에 위치)에 다음 블록을 추가하세요.

{
  "mcpServers": {
    "physbox-mcp": {
      "command": "physbox-mcp",
      "args": ["--stdio"]
    }
  }
}

Claude Code / 로컬 워크스페이스 (.mcp.json)의 경우

프로젝트 루트에 .mcp.json 파일을 추가하거나(또는 ~/.claude/mcp.json의 전역 구성을 업데이트하세요):

{
  "mcpServers": {
    "physbox-mcp": {
      "type": "stdio",
      "command": "physbox-mcp",
      "args": ["--stdio"]
    }
  }
}

소스에서 개발 중이신가요? 클론된 리포지토리나 가상 환경에서 직접 실행하는 경우 Python 인터프리터를 사용하세요.

{
  "mcpServers": {
    "physbox-mcp": {
      "type": "stdio",
      "command": "python",
      "args": ["-m", "physbox_mcp.server", "--stdio"]
    }
  }
}

(필요한 경우 "python"을 가상 환경의 Python 실행 파일 경로(예: /path/to/venv/bin/python)로 바꾸세요).

Google Antigravity IDE의 경우

Windows/WSL 설정에서 Antigravity IDE는 전역 구성 디렉토리에서 구성을 읽습니다. 전역 디렉토리(~/.gemini/config/)는 쓰기가 제한될 수 있으므로 쓰기 가능한 ~/.gemini/antigravity/ 폴더에 연결해야 합니다.

1. PowerShell에서 전역 구성 대상에서 쓰기 가능한 사용자 디렉토리로 하드 링크를 생성하세요.

   # Delete the empty placeholder file if it exists
   Remove-Item -Path "$env:USERPROFILE\.gemini\config\mcp_config.json" -Force -ErrorAction SilentlyContinue
   
   # Create a Hard Link to the writable copy
   New-Item -ItemType HardLink -Path "$env:USERPROFILE\.gemini\config\mcp_config.json" -Target "$env:USERPROFILE\.gemini\antigravity\mcp_config.json"

2. mcp_config.json에 physbox-mcp WSL 구성을 추가하세요(<your-wsl-distro>를 WSL 배포판(예: Ubuntu-20.04)으로 바꾸세요).

   {
     "mcpServers": {
       "physbox-mcp": {
         "command": "C:\\Windows\\system32\\wsl.exe",
         "args": [
           "-d",
           "<your-wsl-distro>",
           "physbox-mcp",
           "--stdio"
         ]
       }
     }
   }

   (WSL에서 소스로 개발하는 경우 args에 가상 환경의 Python 바이너리와 -m physbox_mcp.server를 대신 전달하세요).

3. IDE를 다시 시작하거나(또는 에이전트 채팅 세션을 닫고 다시 로드하여) MCP 도구를 기본적으로 등록하세요.

3. 컴패니언 서버 수동 실행 (선택 사항)

Stdio가 아닌 HTTP 모드로 서버를 실행하는 경우 다음을 실행할 수 있습니다.

# Starts HTTP server listening on port 3141 (default)
physbox-mcp

또는 사용자 정의 포트 매개변수를 구성하세요.

physbox-mcp --port=4000

개발 및 기여

로컬 개발, 스키마 수정, 도구 정의 확장 및 수동 빌드에 대한 지침은 README_DEV.md를 참조하세요.