zackpeters93/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
From source
---
Claude Code setup
Or from source (without pip install):
---
Claude Desktop setup
In ~/Library/Application Support/Claude/claude_desktop_config.json:
Or from source:
---
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