Purpose
ugs-mcp is an MCP (Model Context Protocol) server for controlling CNC machines via Universal GCode Sender (UGS). It allows Claude or any MCP-compatible AI assistant to connect to CNC devices, inspect G-code, and issue motion commands, all through the UGS Pendant REST API.
Main capabilities
- Connection tools: Connect/disconnect UGS and the CNC machine, troubleshoot serial port issues.
- Status tools: Read machine status, position, feed rate, spindle speed.
- Motion tools (token-protected): Jog each axis, home, return to work zero, run G-code files and macros.
- G-code inspector: Translate G-code into English, perform safety checks, estimate cycle time, generate a tool list.
Usage
Requirements
- Universal GCode Sender 2.x (winder.github.io/ugs_website)
- UGS Pendant plugin installed and enabled (Tools → Plugins → Installed)
- Pendant running on http://localhost:8080（默认）
Claude Code setup
Can be run directly from source (no pip install required).
Claude Desktop setup
Configure in ~/Library/Application Support/Claude/claude_desktop_config.json, or run from source.
Environment variables
All optional. Copy .env.example to .env to customize.
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 such as [A3F8B2C1].
- Step 2 — Read the preview. If you agree, tell Claude the token. Claude calls the tool again with confirmation_token="A3F8B2C1", and only then will the machine move.
Tokens are generated by the server via uuid4(), expire after 2 minutes, and can be used only once. Claude cannot predict, forge, or reuse them. Only when you enter the token will motion occur. For the complete tool reference (including parameters, examples, and typical workflows), see USER_GUIDE.md.
Applicable scenarios
Suitable for scenarios where an AI assistant helps operate GRBL-type CNC machines, such as inspecting G-code, estimating machining time, and performing motion operations such as jogging or homing with human confirmation.
Limitations and safety warnings
- Machines controlled by this software can damage equipment, destroy parts, and cause personal injury or even death.
- CNC machines move quickly and are not aware of where your hands are. Before use, you must: read SAFETY.md in full; understand the token confirmation system that prevents Claude from moving the machine autonomously; know the location of the emergency stop.
- If problems occur after only skimming the safety documentation, you do so at your own risk.
- Test environment: SainSmart Genmitsu 3018 Pro (GRBL), UGS 2.x with the Pendant plugin, macOS / Python 3.11. May work with any GRBL-based machine; TinyG/FluidNC/Smoothieware are untested.
- License: MIT, see LICENSE. No warranty, no liability; please read SAFETY.md.
