Metadata-Version: 2.4
Name: ugs-mcp
Version: 0.1.0
Summary: MCP server for controlling CNC machines via Universal GCode Sender
Project-URL: Homepage, https://github.com/zackpeters93/ugs-mcp
Project-URL: Repository, https://github.com/zackpeters93/ugs-mcp
Project-URL: Bug Tracker, https://github.com/zackpeters93/ugs-mcp/issues
Author-email: Zack Peters <zapeters@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Zack Peters
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
License-File: LICENSE
Keywords: claude,cnc,gcode,grbl,mcp,ugs,universal-gcode-sender
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.11
Requires-Dist: httpx>=0.27.0
Requires-Dist: mcp>=1.0.0
Requires-Dist: pyserial>=3.5
Provides-Extra: dev
Requires-Dist: pytest-asyncio>=0.23.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Description-Content-Type: text/markdown

# 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](SAFETY.md). All of it.
- Understand the [token confirmation system](#the-token-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](https://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.git
cd ugs-mcp
pip 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/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](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](LICENSE).

**No warranty. No liability. Read [SAFETY.md](SAFETY.md).**
