{
  "markdown": "# ugs-mcp\n\n[![PyPI version](https://img.shields.io/pypi/v/ugs-mcp.svg)](https://pypi.org/project/ugs-mcp/)\n[![CI](https://github.com/zackpeters93/ugs-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/zackpeters93/ugs-mcp/actions/workflows/ci.yml)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![Python 3.11+](https://img.shields.io/badge/python-3.11+-blue.svg)](https://www.python.org/downloads/)\n[![ugs-mcp MCP server](https://glama.ai/mcp/servers/zackpeters93/ugs-mcp/badges/score.svg)](https://glama.ai/mcp/servers/zackpeters93/ugs-mcp)\n\n**MCP server for controlling CNC machines via Universal GCode Sender.**\n\nLets Claude (or any MCP-compatible AI assistant) connect to a CNC machine, inspect G-code,\nand issue motion commands — all through the UGS Pendant REST API.\n\n---\n\n## ⚠️ STOP. READ THIS FIRST.\n\n**This software controls machines that can damage equipment, destroy parts, and injure or kill people.**\n\nCNC machines move fast and don't know where your hands are. Before you use this:\n\n- Read [SAFETY.md](SAFETY.md). All of it.\n- Understand the [token confirmation system](#the-token-system) that prevents Claude from moving your machine autonomously.\n- Know where your E-stop is.\n\nIf you skim the safety docs and something goes wrong, that's on you. We warned you.\n\n---\n\n## What it does\n\n- **Connection tools** — Connect/disconnect UGS to your CNC, troubleshoot serial port issues\n- **Status tools** — Read machine state, position, feed rate, spindle speed\n- **Motion tools** (token-protected) — Jog axes, home, return to work zero, run G-code files and macros\n- **G-code inspector** — Translate G-code to English, safety check, cycle time estimate, tool list\n\nEvery motion command uses a **two-step token protocol**: Claude generates a token, shows it to you,\nand the machine only moves when you read the token back. Claude cannot bypass this — tokens are\ngenerated and validated server-side.\n\n---\n\n## Requirements\n\n- Universal GCode Sender 2.x ([winder.github.io/ugs_website](https://winder.github.io/ugs_website/))\n- UGS Pendant plugin installed and active (Tools → Plugins → Installed)\n- Pendant running at `http://localhost:8080` (default)\n- Python 3.11+\n\n---\n\n## Installation\n\n### Via pip\n\n```bash\npip install ugs-mcp\n```\n\n### From source\n\n```bash\ngit clone https://github.com/zackpeters93/ugs-mcp.git\ncd ugs-mcp\npip install -e .\n```\n\n---\n\n## Claude Code setup\n\n```bash\nclaude mcp add ugs-cnc ugs-mcp\n```\n\nOr from source (without pip install):\n\n```bash\nclaude mcp add ugs-cnc /path/to/ugs-mcp/ugs_mcp/run_server.sh\n```\n\n---\n\n## Claude Desktop setup\n\nIn `~/Library/Application Support/Claude/claude_desktop_config.json`:\n\n```json\n{\n  \"mcpServers\": {\n    \"ugs-cnc\": {\n      \"command\": \"ugs-mcp\"\n    }\n  }\n}\n```\n\nOr from source:\n\n```json\n{\n  \"mcpServers\": {\n    \"ugs-cnc\": {\n      \"command\": \"/opt/homebrew/opt/python@3.11/libexec/bin/python3\",\n      \"args\": [\"-m\", \"ugs_mcp.server\"],\n      \"cwd\": \"/path/to/ugs-mcp\"\n    }\n  }\n}\n```\n\n---\n\n## Configuration\n\nEnvironment variables (all optional):\n\n| Variable | Default | Description |\n|---|---|---|\n| `UGS_HOST` | `localhost` | UGS Pendant host |\n| `UGS_PORT` | `8080` | UGS Pendant port |\n| `MACROS_DIR` | `ugs_mcp/macros/` | Directory for saved G-code macros |\n| `RAPID_SPEED_MM_MIN` | `5000` | Rapid speed used in return-to-zero |\n\nCopy `.env.example` to `.env` to customize.\n\n---\n\n## The token system\n\nEvery motion tool uses a mandatory two-step confirmation:\n\n**Step 1** — Call the tool without a token. Claude shows you a preview (axis, distance,\nresulting position, safety warnings) and a token like `[A3F8B2C1]`.\n\n**Step 2** — Read the preview. If you agree, tell Claude the token. Claude calls the tool\nagain with `confirmation_token=\"A3F8B2C1\"`. The machine moves.\n\nTokens are generated server-side via `uuid4()`, expire in 2 minutes, and are single-use.\nClaude cannot predict, fabricate, or reuse them. The only way movement happens is if you\ntype the token back.\n\n---\n\n## Tools\n\nSee [USER_GUIDE.md](USER_GUIDE.md) for the full tool reference with parameters, examples,\nand typical workflows.\n\n| Category | Tools |\n|---|---|\n| Connection | `ugs_connect`, `ugs_disconnect`, `ugs_troubleshoot_connection` |\n| Status | `ugs_get_status`, `ugs_get_job_status` |\n| Job | `ugs_run_file`, `ugs_pause_job`, `ugs_cancel_job` |\n| Motion | `ugs_jog`, `ugs_home`, `ugs_return_to_zero`, `ugs_set_work_zero` |\n| G-code | `gcode_safety_check`, `gcode_estimate_time`, `gcode_translate`, `gcode_list_tools`, `gcode_save_macro`, `gcode_list_macros`, `gcode_run_macro` |\n\n---\n\n## Tested with\n\n- SainSmart Genmitsu 3018 Pro (GRBL)\n- UGS 2.x with Pendant plugin\n- macOS / Python 3.11\n\nLikely works with any GRBL-based machine. TinyG/FluidNC/Smoothieware untested.\n\n---\n\n## License\n\nMIT — see [LICENSE](LICENSE).\n\n**No warranty. No liability. Read [SAFETY.md](SAFETY.md).**\n\n<!-- mcp-name: io.github.zackpeters93/ugs-mcp -->\n",
  "bytes": 4919,
  "sha": "293ec2de55c1d31a6ad83100442457041bbfa2325732c4b8c186d62231b6df8f",
  "repo_slug": "zackpeters93/ugs-mcp",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_zackpeters93_ugs_mcp_76cf11bd/readme"
}