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 three 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.

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

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

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

Development & Contribution

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