English Français العربية

io.github.zackpeters93/ugs-mcp

السجل الرسمي أدوات المطورين

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

الشيفرة المصدرية التوثيق

ماذا يمكنك أن تفعل مع io.github.zackpeters93/ugs-mcp؟

  • 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

التثبيت

أضف هذا إلى إعدادات MCP في عميلك (Claude Desktop: claude_desktop_config.json، وCursor: ‏.cursor/mcp.json، ويستخدم VS Code وغيره الصيغة نفسها «mcpServers»).

PYPI package ugs-mcp
Claude Code 
claude mcp add ugs-mcp -e 'UGS_HOST=<UGS_HOST>' -e 'UGS_PORT=<UGS_PORT>' -e 'MACROS_DIR=<MACROS_DIR>' -e 'RAPID_SPEED_MM_MIN=<RAPID_SPEED_MM_MIN>' -- uvx ugs-mcp==0.1.1
إعداد JSON (Claude Desktop وCursor وVS Code) 
{
    "mcpServers": {
        "ugs-mcp": {
            "command": "uvx",
            "args": [
                "ugs-mcp==0.1.1"
            ],
            "env": {
                "UGS_HOST": "<UGS_HOST>",
                "UGS_PORT": "<UGS_PORT>",
                "MACROS_DIR": "<MACROS_DIR>",
                "RAPID_SPEED_MM_MIN": "<RAPID_SPEED_MM_MIN>"
            }
        }
    }
}

متغيرات البيئة

  • UGS_HOST UGS Pendant host address
  • UGS_PORT UGS Pendant port (default: 8080)
  • MACROS_DIR Directory for saved G-code macros
  • RAPID_SPEED_MM_MIN Rapid speed in mm/min used for return-to-zero (default: 5000)

التوثيق

مأخوذ من ملف README للمشروع على GitHub ويُحدَّث أسبوعيًا. تفتح الروابط على GitHub.

المحتويات
  1. ugs-mcp
  2. ⚠️ STOP. READ THIS FIRST.
  3. What it does
  4. Requirements
  5. Installation
  6. Claude Code setup
  7. Claude Desktop setup
  8. Configuration
  9. The token system
  10. Tools
  11. Tested with
  12. License

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:

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):

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.

الأسئلة الشائعة

ما هو io.github.zackpeters93/ugs-mcp؟

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

كيف أثبّت io.github.zackpeters93/ugs-mcp؟

يعمل على جهازك. في Claude Code: claude mcp add ugs-mcp -e 'UGS_HOST=<UGS_HOST>' -e 'UGS_PORT=<UGS_PORT>' -e 'MACROS_DIR=<MACROS_DIR>' -e 'RAPID_SPEED_MM_MIN=<RAPID_SPEED_MM_MIN>' -- uvx ugs-mcp==0.1.1. وفي العملاء الآخرين، الصق إعداد JSON من هذه الصفحة في إعدادات MCP الخاصة بهم.

هل يحتاج io.github.zackpeters93/ugs-mcp إلى مفتاح API؟

لا يذكر إدراجه في السجل أي مفتاح أو سر إلزامي. قد تتطلب بعض الميزات حسابًا لدى الخدمة التي يتصل بها.

هل io.github.zackpeters93/ugs-mcp مفتوح المصدر؟

نعم. شيفرته متاحة على GitHub بترخيص MIT.

من يصون io.github.zackpeters93/ugs-mcp؟

ينشره zackpeters93. يدرجه AI.tn لكنه لا يصونه ولا يوصي به.

من سجل MCP الرسمي. الإدراج ليس توصية: راجع شيفرة الخادم وصلاحياته قبل منحه الوصول إلى بياناتك.