PhysBox: MCP

PhysBox: MCP 是一个模型上下文协议（MCP）服务器，使LLM和MCP客户端（如Claude Code或Claude Desktop）能够通过浏览器程序化地与四个模拟Web应用交互：

所有通信均通过JSON在WebSocket上直接传输到浏览器中的Web应用——无需浏览器自动化或DOM抓取。

🧠 唯一的AI原生物理世界模型

与静态代码生成或离线文件输出不同，PhysBox为AI智能体提供了一个交互式的真实世界模型。LLM执行81种类型化工具调用，以观察空间运动学、电路节点波形和G代码安全警告，使其能够迭代地自我修正设计。

💬 Claude Code与Cursor的示例智能体提示

直接将这些提示粘贴到连接MCP的智能体中：

• Volt (Electronics):

  "优化有源Volt原理图中的RC滤波器值，以实现1 kHz截止频率，然后执行circuit_run_sim并绘制幅度响应。"

• Mesh (3D Physics & CAD):

  "在Mesh中编写一个带有4mm螺丝孔的OpenSCAD参数化安装支架，使用physics_check_collisions运行MuJoCo碰撞稳定性检查，并导出Z轴向上的STL。"

• Etch (CNC & Laser):

  "导入此矢量SVG标志，为胶合板应用2次3mm下切进给，检查立铣刀安全警告，并生成GRBL G代码。"

Related MCP server: Tesseron

工作原理

PhysBox: MCP 作为一个本地伴生服务器，在端口3142上建立WebSocket中继。

当你打开任何模拟Web应用时，它们会直接连接到此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. 打开Web应用

在浏览器中启动或访问模拟Web应用：

• 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. 将physbox-mcp WSL配置添加到你的mcp_config.json（将<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. 手动运行伴生服务器（可选）

如果你以HTTP模式而非Stdio模式运行服务器，可以运行：

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

或配置自定义端口参数：

physbox-mcp --port=4000

开发与贡献

有关本地开发、修改模式、扩展工具定义和手动构建的说明，请参阅README_DEV.md。