ugs-mcp

MCP server for controlling CNC machines via Universal GCode Sender.

Lets Claude (or any MCP-compatible AI assistant) connect to a CNC machine, inspect G-code, and issue motion commands — all through the UGS Pendant REST API.

⚠️ STOP. READ THIS FIRST.

This software controls machines that can damage equipment, destroy parts, and injure or kill people.

CNC machines move fast and don't know where your hands are. Before you use this:

Read SAFETY.md. All of it.
Understand the token confirmation system that prevents Claude from moving your machine autonomously.
Know where your E-stop is.

If you skim the safety docs and something goes wrong, that's on you. We warned you.

What it does

Connection tools — Connect/disconnect UGS to your CNC, troubleshoot serial port issues
Status tools — Read machine state, position, feed rate, spindle speed
Motion tools (token-protected) — Jog axes, home, return to work zero, run G-code files and macros
G-code inspector — Translate G-code to English, safety check, cycle time estimate, tool list

Every motion command uses a two-step token protocol: Claude generates a token, shows it to you, and the machine only moves when you read the token back. Claude cannot bypass this — tokens are generated and validated server-side.

Requirements

Universal GCode Sender 2.x (winder.github.io/ugs_website)
UGS Pendant plugin installed and active (Tools → Plugins → Installed)
Pendant running at http://localhost:8080 (default)
Python 3.11+

Installation

Via pip

Terminal

pip install ugs-mcp

From source

bash

git clone https://github.com/zackpeters93/ugs-mcp.git
cd ugs-mcp
pip install -e .

Claude Code setup

Terminal

claude mcp add ugs-cnc ugs-mcp

Or from source (without pip install):

Terminal

claude mcp add ugs-cnc /path/to/ugs-mcp/ugs_mcp/run_server.sh

Claude Desktop setup

In ~/Library/Application Support/Claude/claude_desktop_config.json:

config.json

{
  "mcpServers": {
    "ugs-cnc": {
      "command": "ugs-mcp"
    }
  }
}

Or from source:

config.json

{
  "mcpServers": {
    "ugs-cnc": {
      "command": "/opt/homebrew/opt/python@3.11/libexec/bin/python3",
      "args": ["-m", "ugs_mcp.server"],
      "cwd": "/path/to/ugs-mcp"
    }
  }
}

Configuration

Environment variables (all optional):

Variable	Default	Description
`UGS_HOST`	`localhost`	UGS Pendant host
`UGS_PORT`	`8080`	UGS Pendant port
`MACROS_DIR`	`ugs_mcp/macros/`	Directory for saved G-code macros
`RAPID_SPEED_MM_MIN`	`5000`	Rapid speed used in return-to-zero

Copy .env.example to .env to customize.

The token system

Every motion tool uses a mandatory two-step confirmation:

Step 1 — Call the tool without a token. Claude shows you a preview (axis, distance, resulting position, safety warnings) and a token like [A3F8B2C1].

Step 2 — Read the preview. If you agree, tell Claude the token. Claude calls the tool again with confirmation_token="A3F8B2C1". The machine moves.

Tokens are generated server-side via uuid4(), expire in 2 minutes, and are single-use. Claude cannot predict, fabricate, or reuse them. The only way movement happens is if you type the token back.

Tools

See USER_GUIDE.md for the full tool reference with parameters, examples, and typical workflows.

Category	Tools
Connection	`ugs_connect`, `ugs_disconnect`, `ugs_troubleshoot_connection`
Status	`ugs_get_status`, `ugs_get_job_status`
Job	`ugs_run_file`, `ugs_pause_job`, `ugs_cancel_job`
Motion	`ugs_jog`, `ugs_home`, `ugs_return_to_zero`, `ugs_set_work_zero`
G-code	`gcode_safety_check`, `gcode_estimate_time`, `gcode_translate`, `gcode_list_tools`, `gcode_save_macro`, `gcode_list_macros`, `gcode_run_macro`

Tested with

SainSmart Genmitsu 3018 Pro (GRBL)
UGS 2.x with Pendant plugin
macOS / Python 3.11

Likely works with any GRBL-based machine. TinyG/FluidNC/Smoothieware untested.

License

MIT — see LICENSE.

No warranty. No liability. Read SAFETY.md.