Ugs MCP

What zackpeters93/ugs-mcp does

The zackpeters93/ugs-mcp MCP server links an MCP-compatible assistant with a CNC machine managed by Universal GCode Sender (UGS). It communicates through the UGS Pendant REST API rather than directly controlling the machine’s serial connection. The documented target is GRBL-based CNC equipment, with testing reported on a SainSmart Genmitsu 3018 Pro.

The server covers both machine operation and offline G-code inspection. An assistant can connect to or disconnect from UGS, inspect machine and job status, and troubleshoot serial connection issues. It can also request axis jogs, homing, return-to-work-zero, work-zero setting, job execution, pausing, cancellation, and macro execution. Inspection tools translate G-code into plain language, check it for safety issues, estimate cycle time, and list tools.

Because these capabilities can move physical equipment, operation is intended to remain under human supervision. The project documentation warns that incorrect use can damage equipment, ruin parts, or cause injury.

How it works

UGS Pendant is expected to be running locally, normally at http://localhost:8080. The MCP process sends requests to that endpoint, while the MCP client presents the resulting tools to the assistant.

Motion tools use a two-step confirmation flow. The first call does not move the machine; instead, the server returns a preview containing details such as the requested axis or distance, resulting position, warnings, and a confirmation token. The operator must provide that token in a second call. Tokens are generated by the server, expire after two minutes, and can be used only once. This design means the assistant cannot complete a motion request without the operator reading back the displayed token.

Setup and configuration

Install Python 3.11 or newer, Universal GCode Sender 2.x, and the UGS Pendant plugin. Start Pendant and verify its host and port before launching the MCP process. The package can be installed with pip, after which the ugs-mcp executable can be registered with an MCP client.

The zackpeters93/ugs-mcp configuration uses optional environment variables. UGS_HOST selects the Pendant host and defaults to localhost; UGS_PORT defaults to 8080. MACROS_DIR identifies the directory used for saved G-code macros, while RAPID_SPEED_MM_MIN controls the rapid speed used by return-to-zero and defaults to 5000. The repository provides a .env.example file as a configuration reference.

Claude Desktop can launch the installed ugs-mcp command from its MCP server configuration. The README also documents a source-based Python module setup. Read the project’s safety documentation and confirm the physical emergency stop location before using motion functions.

Tools and capabilities

The available tools are grouped as follows:

• Connection: ugs_connect, ugs_disconnect, and ugs_troubleshoot_connection
• Status: ugs_get_status and ugs_get_job_status
• Jobs: ugs_run_file, ugs_pause_job, and ugs_cancel_job
• Motion: ugs_jog, ugs_home, ugs_return_to_zero, and ugs_set_work_zero
• G-code: gcode_safety_check, gcode_estimate_time, gcode_translate, gcode_list_tools, gcode_save_macro, gcode_list_macros, and gcode_run_macro

The project was tested with UGS 2.x, the Pendant plugin, macOS, and Python 3.11. GRBL compatibility is the documented target. TinyG, FluidNC, and Smoothieware are listed as untested, so support for those controllers should not be assumed.

Getting started with this zackpeters93/ugs-mcp MCP server

Always refer to the official documentation for the most accurate and up-to-date information.