ugs-mcp — Claude Code MCP server for CNC control
Connect an AI agent to a CNC machine through Universal GCode Sender to inspect G-code, check machine status, and request motion with your confirmation.
claude mcp add --env UGS_HOST=<UGS_HOST> --env UGS_PORT=<UGS_PORT> --env MACROS_DIR=<MACROS_DIR> --env RAPID_SPEED_MM_MIN=<RAPID_SPEED_MM_MIN> --transport stdio ugs-mcp -- uvx ugs-mcpWhat ugs-mcp does
The server connects an agent to Universal GCode Sender through the Pendant REST API. It can read machine status, position, feed rate, and spindle speed; inspect G-code; estimate cycle time; and handle jobs, macros, and axis movement.
Motion requires a confirmation token for each command. The agent first presents a preview and token; the machine moves only after you return that token. Tokens are single-use and expire after 2 minutes. This safeguard does not replace reading SAFETY.md or knowing where the emergency stop is.
You need Universal GCode Sender 2.x with the Pendant plugin active, plus Python 3.11+. Pendant uses localhost:8080 by default, and environment variables let you change the connection settings. The project reports testing with a SainSmart Genmitsu 3018 Pro running GRBL.
What it helps with
- inspect G-code for safety issues before running it
- check machine status and current position
- jog an axis after reviewing a confirmation token
- run a G-code file or macro through UGS
Example prompts for the agent
- Check this G-code for safety issues and estimate its cycle time.
- Show the machine status and current position.
- Prepare a 5 mm move on the X axis and show me the confirmation token.
How to install ugs-mcp
Platform CLI
claude mcp add --env UGS_HOST=<UGS_HOST> --env UGS_PORT=<UGS_PORT> --env MACROS_DIR=<MACROS_DIR> --env RAPID_SPEED_MM_MIN=<RAPID_SPEED_MM_MIN> --transport stdio ugs-mcp -- uvx ugs-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from ugs-mcp <command>
Platform CLI
codex mcp add ugs-mcp --env UGS_HOST=<UGS_HOST> --env UGS_PORT=<UGS_PORT> --env MACROS_DIR=<MACROS_DIR> --env RAPID_SPEED_MM_MIN=<RAPID_SPEED_MM_MIN> -- uvx ugs-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from ugs-mcp <command>
Config file
{
"mcpServers": {
"ugs-mcp": {
"command": "uvx",
"args": [
"ugs-mcp"
],
"env": {
"UGS_HOST": "<UGS_HOST>",
"UGS_PORT": "<UGS_PORT>",
"MACROS_DIR": "<MACROS_DIR>",
"RAPID_SPEED_MM_MIN": "<RAPID_SPEED_MM_MIN>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from ugs-mcp <command>
Config file
{
"servers": {
"ugs-mcp": {
"type": "stdio",
"command": "uvx",
"args": [
"ugs-mcp"
],
"env": {
"UGS_HOST": "<UGS_HOST>",
"UGS_PORT": "<UGS_PORT>",
"MACROS_DIR": "<MACROS_DIR>",
"RAPID_SPEED_MM_MIN": "<RAPID_SPEED_MM_MIN>"
}
}
}
}Replace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from ugs-mcp <command>
Platform CLI
gemini mcp add -e UGS_HOST=<UGS_HOST> -e UGS_PORT=<UGS_PORT> -e MACROS_DIR=<MACROS_DIR> -e RAPID_SPEED_MM_MIN=<RAPID_SPEED_MM_MIN> ugs-mcp uvx ugs-mcpReplace <…> with your own values. uvx runs the command named after the package; if the README names another one, use uvx --from ugs-mcp <command>
Step by step, with commands for each platform: How to add an MCP server to Claude Code, Codex, Cursor, VS Code, Gemini CLI and more
Questions about ugs-mcp
How do I install ugs-mcp in Claude Code?
Run claude mcp add ugs-mcp -- uvx ugs-mcp. Set up Universal GCode Sender 2.x and activate its Pendant plugin before connecting.
What does ugs-mcp do?
It lets an AI agent inspect G-code and machine status, then control a CNC machine through UGS Pendant. Motion tools require a token that you review and return before the machine moves.
What does ugs-mcp need to run?
It requires Universal GCode Sender 2.x, the active Pendant plugin, and Python 3.11+. The documented default Pendant address is localhost:8080.
