Ugs Mcp

io.github.zackpeters93Published by GitHub account zackpeters93v0.1.1Updated Oct 24, 2026

CNC machine control via Universal G-code Sender. Jog, home, run files with hardware safety tokens.

VerifiedSTDIODesktop onlyCloud & InfrastructureDeveloper Tools

Overview

AI-generated overview

Controls a CNC machine through Universal G-code Sender: jog, home, run files and macros, and inspect G-code, with token-confirmed motion.

What you can do
Connects an assistant to a CNC machine over the UGS Pendant REST API. Connection tools link or unlink UGS and help troubleshoot serial ports; status tools report machine state, position, feed rate and spindle speed. Motion tools jog axes, home, return to work zero, set work zero, and run G-code files or saved macros. A G-code inspector translates G-code to English, runs safety checks, estimates cycle time and lists tools.
When to use it
Use it when you want an assistant to drive or inspect a GRBL-based CNC machine already running UGS with the Pendant plugin, for example to jog, home, run a job, or check G-code before cutting. It is not useful without a connected machine and UGS setup.
Requirements
Local Python 3.11+ process installed from PyPI or source. Universal GCode Sender 2.x with the UGS Pendant plugin active, reachable at the configured host and port. Optional environment variables: UGS_HOST, UGS_PORT, MACROS_DIR, RAPID_SPEED_MM_MIN. No accounts or API keys declared.
Before you install
This server moves real machinery that can damage equipment, ruin parts, and injure or kill people. Motion commands require a two-step confirmation token that the user must read back, but running files, macros, homing and zero-setting still change machine state. Review the safety documentation and know where the emergency stop is before use.

Installation

In SourceWeft

  1. Open Ugs Mcp in the dashboard and add it to a workspace.
  2. Enable the server for the chats that should use its tools.

Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.

Other MCP clients

Follow the launch instructions in the repository.

README

ugs-mcp

[PyPI version] [CI] [License: MIT] [Python 3.11+] [ugs-mcp MCP server]

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:

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

bash
pip install ugs-mcp

From source

bash
git clone https://github.com/zackpeters93/ugs-mcp.gitcd ugs-mcppip install -e .

Claude Code setup

bash
claude mcp add ugs-cnc ugs-mcp

Or from source (without pip install):

bash
claude mcp add ugs-cnc /path/to/ugs-mcp/ugs_mcp/run_server.sh

Claude Desktop setup

In ~/Library/Application Support/Claude/claude_desktop_config.json:

json
{  "mcpServers": {    "ugs-cnc": {      "command": "ugs-mcp"    }  }}

Or from source:

json
{  "mcpServers": {    "ugs-cnc": {      "command": "/opt/homebrew/opt/[email protected]/libexec/bin/python3",      "args": ["-m", "ugs_mcp.server"],      "cwd": "/path/to/ugs-mcp"    }  }}

Configuration

Environment variables (all optional):

VariableDefaultDescription
UGS_HOSTlocalhostUGS Pendant host
UGS_PORT8080UGS Pendant port
MACROS_DIRugs_mcp/macros/Directory for saved G-code macros
RAPID_SPEED_MM_MIN5000Rapid 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 type the token back.

Tools

See USER_GUIDE.md for the full tool reference with parameters, examples, and typical workflows.

CategoryTools
Connectionugs_connect, ugs_disconnect, ugs_troubleshoot_connection
Statusugs_get_status, ugs_get_job_status
Jobugs_run_file, ugs_pause_job, ugs_cancel_job
Motionugs_jog, ugs_home, ugs_return_to_zero, ugs_set_work_zero
G-codegcode_safety_check, gcode_estimate_time, gcode_translate, gcode_list_tools, gcode_save_macro, gcode_list_macros, gcode_run_macro

Tested with

  • SainSmart Genmitsu 3018 Pro (GRBL)
  • UGS 2.x with Pendant plugin
  • macOS / Python 3.11

Likely works with any GRBL-based machine. TinyG/FluidNC/Smoothieware untested.

License

MIT — see LICENSE.

No warranty. No liability. Read SAFETY.md.

Source: README.md at commit ec3f442

Tools

0
SourceWeft has not started this package in its sandbox yet, so its tools are not known.

Version history

1
  1. v0.1.1LatestSep 16, 2026

Score

50% of the applicable checks met

How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.

  • Reached in the last 30 days25 pts

    Keep the endpoint answering the MCP handshake; SourceWeft probes it every 30 days.

  • Auth declared10 pts

    Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.

  • Tools listed15 pts

    Answer tools/list without a credential, or ship a package that starts in a sandbox without one.

  • DescriptionRequired15 pts
  • Logo10 pts
  • Documentation15 pts
  • License10 pts