How do I install Ugs?

Ugs is a local plugin. Install it using PyPI package: ugs-mcp and add the generated configuration snippet to your AI app's MCP config file. Then restart your AI app.

What credentials does Ugs need?

Ugs requires the following credentials or environment variables: UGS_HOST, UGS_PORT, MACROS_DIR, RAPID_SPEED_MM_MIN. You can find setup instructions on the server detail page.

What AI apps work with Ugs?

Ugs uses the Model Context Protocol (MCP) and works with any MCP-compatible AI app, including Claude, ChatGPT / Codex, Gemini, Copilot, Cursor, and more.

Back to Browse

Ugs MCP Server

by Zackpeters93

Developer ToolsUse Caution4.8MCP RegistryLocal

Free

Server data from the Official MCP Registry

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

About

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

Security Report

4.8

Use Caution4.8High Risk

ugs-mcp is a well-designed CNC machine controller MCP server with strong safety-first architecture. The codebase implements a robust two-step token confirmation system that prevents unauthorized machine movement by requiring user intervention for all motion commands. Code quality is good with proper error handling, input validation, and clear separation of concerns. Permissions align well with the server's purpose of controlling CNC machines via REST APIs. Minor code quality improvements around exception handling and logging are recommended but do not pose security risks. Supply chain analysis found 4 known vulnerabilities in dependencies (0 critical, 3 high severity). Package verification found 1 issue.

8 files analyzed · 11 issues found

Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.

Permissions Required

This plugin requests these system permissions. Most are normal for its category.

HTTP Network Access

Connects to external APIs or services over the internet.

env_vars

Check that this permission is expected for this type of plugin.

File System Read

Reads files on your machine. Normal for tools that analyze or process local data.

File System Write

Writes or modifies files on your machine. Check that this is expected for the tool.

What You'll Need

Set these up before or after installing:

UGS Pendant host addressOptional

Environment variable: UGS_HOST

UGS Pendant port (default: 8080)Optional

Environment variable: UGS_PORT

Directory for saved G-code macrosOptional

Environment variable: MACROS_DIR

Rapid speed in mm/min used for return-to-zero (default: 5000)Optional

Environment variable: RAPID_SPEED_MM_MIN

How to Install

Add this to your MCP configuration file:

{
  "mcpServers": {
    "io-github-zackpeters93-ugs-mcp": {
      "env": {
        "UGS_HOST": "your-ugs-host-here",
        "UGS_PORT": "your-ugs-port-here",
        "MACROS_DIR": "your-macros-dir-here",
        "RAPID_SPEED_MM_MIN": "your-rapid-speed-mm-min-here"
      },
      "args": [
        "ugs-mcp"
      ],
      "command": "uvx"
    }
  }
}

Documentation

View on GitHub

From the project's GitHub README.

ugs-mcp

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:

Read SAFETY.md. All of it.
Understand the token confirmation system that prevents Claude from moving your machine autonomously.
Know where your E-stop is.

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

pip install ugs-mcp

From source

git clone https://github.com/zackpeters93/ugs-mcp.git
cd ugs-mcp
pip install -e .

Claude Code setup

claude mcp add ugs-cnc ugs-mcp

Or from source (without pip install):

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:

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

Or from source:

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

Configuration

Environment variables (all optional):

Variable	Default	Description
`UGS_HOST`	`localhost`	UGS Pendant host
`UGS_PORT`	`8080`	UGS Pendant port
`MACROS_DIR`	`ugs_mcp/macros/`	Directory for saved G-code macros
`RAPID_SPEED_MM_MIN`	`5000`	Rapid 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.

Category	Tools
Connection	`ugs_connect`, `ugs_disconnect`, `ugs_troubleshoot_connection`
Status	`ugs_get_status`, `ugs_get_job_status`
Job	`ugs_run_file`, `ugs_pause_job`, `ugs_cancel_job`
Motion	`ugs_jog`, `ugs_home`, `ugs_return_to_zero`, `ugs_set_work_zero`
G-code	`gcode_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.

Reviews

No reviews yet

Be the first to review this server!

More Developer Tools MCP Servers

Git

Free

by Modelcontextprotocol · Developer Tools

Read, search, and manipulate Git repositories programmatically

Fetch

Free

by Modelcontextprotocol · Developer Tools

Web content fetching and conversion for efficient LLM usage

Toleno

Free

by Toleno · Developer Tools

Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.

Ugs MCP Server

About

Security Report

Findings (11)Action required

Permissions Required

What You'll Need

How to Install

Documentation

ugs-mcp

⚠️ STOP. READ THIS FIRST.

What it does

Requirements

Installation

Via pip

From source

Claude Code setup

Claude Desktop setup

Configuration

The token system

Tools

Tested with

License

Reviews

No reviews yet

More Developer Tools MCP Servers

Git

Fetch

Toleno

mcp-creator-python

MarkItDown

FinAgent