Installation

This guide gets the PhysiClaw server running and connected to your agent. You’ll need the hardware assembled, a phone in the cradle, and Python 3.11+.

Install the server

1. Install the Python dependencies.

   bash

   pip install pyserial opencv-python mcp

2. Clone the repository.

   bash

   git clone https://github.com/physiclaw/PhysiClaw.git
   cd PhysiClaw

3. Confirm the layout.

   • Directoryphysiclaw/

     • physiclaw_server.py MCP server entry point
     • hand.py serial G-code control
     • eyes.py USB camera capture
     • config.py configuration constants

Connect the hardware

1. Plug the GRBL board, top camera, and side camera into the USB hub, and the hub into your computer.

2. Find the serial port and camera indices, then set them in config.py:

   macOS

   bash

   ls /dev/tty.usb*        # e.g. /dev/tty.usbserial-1420

   Linux

   bash

   ls /dev/ttyUSB* /dev/ttyACM*

3. Start the server to verify it reaches the board and both cameras:

   bash

   python -m physiclaw.physiclaw_server --check

Permissions

On Linux, add your user to the dialout group (sudo usermod -aG dialout $USER) and re-log so the server can open the serial port without sudo.

Register with your agent

Add PhysiClaw to your MCP client. For Claude Desktop, edit claude_desktop_config.json:

json

{
  "mcpServers": {
    "physiclaw": {
      "command": "python",
      "args": ["-m", "physiclaw.physiclaw_server"]
    }
  }
}

Restart the client. The PhysiClaw tools — screenshot_top, move, tap, swipe, park — should now be available. Continue to the Quickstart.