# grbl-mcp

An [MCP](https://modelcontextprotocol.io/) server that lets Claude (and other MCP clients) control GRBL-based CNC machines over serial.

## Tools

| Tool | Description |
|------|-------------|
| `probe_device` | Identify the CNC controller by reading its startup banner and firmware info |
| `status` | Query machine state and XYZ position (machine and work coordinates) |
| `home` | Execute the homing cycle (`$H`) — moves to limit switches |
| `move_relative` | Incremental move (G91) on any combination of X, Y, Z axes |
| `move_absolute` | Absolute move (G90) on any combination of X, Y, Z axes |

All positions are in millimeters. Moves default to rapid traverse (G00), or use controlled feed (G01) when `feed_rate` (mm/min) is provided.

## Setup

### Prerequisites

- A GRBL-compatible CNC controller connected via USB serial
- Linux with `libudev` (for serial port access)

### Install

```bash
cargo install grbl-mcp
```

Or build from source:

```bash
cargo build --release
```

### Configure

Add to your MCP client configuration (e.g. `.mcp.json`):

```json
{
  "mcpServers": {
    "grbl-mcp": {
      "command": "grbl-mcp"
    }
  }
}
```

The server connects to `/dev/ttyUSB0` at 115200 baud. Ensure your user has permission to access the serial port (e.g., membership in the `dialout` group).

## How it works

The server communicates over stdio using JSON-RPC (MCP protocol) and translates tool calls into G-code commands sent to the CNC controller over serial.

```
MCP client <-- stdio (JSON-RPC) --> grbl-mcp <-- serial (G-code) --> CNC controller
```

## License

GPL-3.0-or-later
