PhysBox: MCP

PhysBox: MCP is a Model Context Protocol (MCP) server that enables LLMs and MCP clients (such as Claude Code or Claude Desktop) to interact programmatically with the four simulation web applications in the browser:

All communication is handled via JSON over WebSockets directly to the web app in your browser—no browser automation or DOM scraping is needed.

🧠 The Only AI-Native Physical World Model

Unlike static code generation or offline file outputs, PhysBox gives AI agents an interactive ground-truth world model. LLMs execute 117 typed tool calls to observe spatial kinematics, circuit node waveforms, and G-code safety warnings, allowing them to self-correct designs iteratively.

💬 Example Agent Prompts for Claude Code & Cursor

Paste any of these prompts directly into your MCP-connected agent:

• Volt (Electronics):

  "Optimize the RC filter values in the active Volt schematic to achieve a 1 kHz cutoff frequency, then execute circuit_run_sim and plot the magnitude response."

• Mesh (3D Physics & CAD):

  "Write an OpenSCAD parametric mounting bracket in Mesh with 4mm screw holes, run a MuJoCo collision stability check using physics_check_collisions, and export the Z-up STL."

• Etch (CNC & Laser):

  "Import this vector SVG logo, apply 2-pass 3mm stepdown feeds for Plywood, check end mill safety warnings, and generate GRBL G-code."

• Your own workshop history (needs a token — see below; no app has to be open):

  "What did I cut that walnut tray at in March?" "Summarise last month's jobs — how much cutting time, and how many failed?" "That engrave that alarmed out yesterday: what line did it stop on, and what was the feed?"

How It Works

PhysBox: MCP functions as a local companion server that establishes a WebSocket relay on port 3142.

When you open any of the simulation web apps, they connect directly to this WebSocket relay. When an MCP client executes a tool call, the command flows from the client to the companion server, gets forwarded to the active browser tab, and the results flow back.

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

Installation

Install the companion server directly from PyPI:

pip install physbox-mcp

Usage & Setup

1. Open the Web Applications

Launch or access the simulation web applications in your web browser:

• Flux: flux.physbox.io
• Volt: volt.physbox.io
• Mesh: mesh.physbox.io
• Etch: etch.physbox.io

As soon as a page finishes loading, it automatically registers with the companion WebSocket server.

2. Configure Your MCP Client

For Claude Desktop

Add the following block to your Claude Desktop configuration file (typically located at AppData/Roaming/Claude/claude_desktop_config.json on Windows or ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

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

For Claude Code / Local Workspace (.mcp.json)

Add a .mcp.json file to your project root (or update your global configuration at ~/.claude/mcp.json):

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

Developing from source? If running directly from a cloned repository or virtual environment, use your Python interpreter:

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

(Replace "python" with the path to your virtual environment's Python executable if needed, e.g. /path/to/venv/bin/python).

For Google Antigravity IDE

On Windows/WSL setups, Antigravity IDE reads configuration from the global configuration directory. Because the global directory (~/.gemini/config/) may be write-restricted, you should link it to the writable ~/.gemini/antigravity/ folder:

1. In PowerShell, create a Hard Link from the global configuration target to the writable user directory:

   # 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. Add the physbox-mcp WSL configuration to your mcp_config.json (replacing <your-wsl-distro> with your WSL distribution such as Ubuntu-20.04):

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

   (If developing from source in WSL, pass your virtual environment's Python binary and -m physbox_mcp.server in args instead).

3. Restart the IDE (or close and reload the agent chat session) to register the MCP tools natively.

3. Run the Companion Server Manually (Optional)

If you are running the server in HTTP mode rather than Stdio, you can run:

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

Or configure custom port parameters:

physbox-mcp --port=4000

☁️ Cloud Tools — your own job history

Everything above drives a browser tab over ws://localhost:3142. It needs no account, no token and no configuration: open an app, and the tools work.

There is a second, smaller set that works the other way round. The physbox_* tools read your PhysBox account over HTTPS, so they answer questions about jobs that finished weeks ago — with no app open at all:

These need PhysBox Pro, because they read the run archive and the cloud documents that Pro records. The 107 local tools above need nothing. If the account is free, the tools say so explicitly — including that nothing was ever archived for it — rather than returning an empty list that would read as "you never cut that".

Setting it up

Mint a read token at physbox.io/history.html and put it in the server's env block. This is the documented path because it is the one thing that behaves identically on Windows, WSL, macOS and Linux:

{
  "mcpServers": {
    "physbox-mcp": {
      "type": "stdio",
      "command": "physbox-mcp",
      "args": ["--stdio"],
      "env": {
        "PHYSBOX_API_TOKEN": "pbx_..."
      }
    }
  }
}

The token is read-only: it can read your runs and documents, and it cannot drive a machine. Revoke it from the same page at any time — tokens are checked per request, so revoking takes effect immediately.

Alternatively, hand the token to your agent once and ask it to call physbox_set_token, which saves it to:

Same shape as PhysBox Native's own config directory (%APPDATA%\physbox-native / ~/.config/physbox-native), so if you have found one you can guess the other.

On WSL: the server and your browser are effectively on two different machines, with two different home directories — only localhost forwarding makes the browser leg work at all. The token belongs on the WSL side, where physbox-mcp actually runs. This is exactly why the env block above is the recommended route rather than the file.

As a last resort, a signed-in app tab offers its own session to the server during its handshake, so the cloud tools work with nothing configured while an app is open. It is last on purpose: the relay has no origin check, and it binds 127.0.0.1 only.

PHYSBOX_API_URL points the tools at a different API (http://localhost:3000 for local development).

Development & Contribution

For instructions on local development, modifying schemas, extending tool definitions, and manual builds, please refer to README_DEV.md.

📜 License

Distributed under the PhysBox Permissive Public License (PPPL-1.0).

Free for personal, educational, research, and commercial use, including commercial sale of anything you produce with it. Redistributing or hosting the software itself as a standalone or competing product requires prior written authorization. See LICENSE for full terms, including the machinery and hardware safety disclaimer.