grbl-mcp

An MCP 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

cargo install grbl-mcp

Or build from source:

cargo build --release

Configure

Add to your MCP client configuration (e.g. .mcp.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