# zackpeters93/ugs-mcp [Health: Active]

**Category:** 📟 Embedded System  
**Repository:** https://github.com/zackpeters93/ugs-mcp  
**GitHub Stars:** 5  
**Views:** 3  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/zackpeters93-ugs-mcp

## Description
CNC machine control via Universal G-code Sender (GRBL). Jog axes, home, run G-code files, inspect toolpaths, estimate cycle times. Motion commands require two-step token confirmation — Claude cannot move hardware autonomously.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `uvx` (confidence: high):

```json
"mcpServers": {
  "ugs-mcp": {
    "command": "uvx",
    "args": ["ugs-mcp"],
    "env": {
      "UGS_HOST": "",
      "UGS_PORT": "",
      "MACROS_DIR": "",
      "RAPID_SPEED_MM_MIN": ""
    }
  }
}
```

**Requires environment variables:** `UGS_HOST`, `UGS_PORT`, `MACROS_DIR`, `RAPID_SPEED_MM_MIN` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## 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.

_Full upstream README: https://allmcps.com/mcp/zackpeters93-ugs-mcp/readme_