ugs-mcp

ugs-mcp

通过 Universal GCode Sender 控制 CNC 机器的 MCP 服务。

让 Claude（或任何兼容 MCP 的 AI 助手）连接到 CNC 机器、检查 G-code， 并发出运动命令——所有操作均通过 UGS Pendant REST API 完成。

---

⚠️ 停下，先阅读。

本软件用于控制机器，这些机器可能损坏设备、毁坏工件，并造成人员受伤甚至死亡。

CNC 机器移动速度很快，而且不知道你的手在哪里。使用前请：

• 阅读 SAFETY.md 中的全部内容。
• 了解可防止 Claude 自主移动机器的令牌确认系统。
• 确认急停按钮的位置。

如果你只是匆匆浏览安全文档，出了问题，责任由你承担。我们已经提醒过你。

---

功能

• 连接工具 — 将 UGS 连接到 CNC 机器或断开连接，并排查串行端口问题
• 状态工具 — 读取机器状态、位置、进给速度和主轴转速
• 运动工具（受令牌保护）— 移动各轴、回零、返回工件零点，以及运行 G-code 文件和宏
• G-code 检查器 — 将 G-code 转译为英语、进行安全检查、估算循环时间并列出工具

每条运动命令都采用两步令牌协议：Claude 生成令牌并展示给你，只有你读回令牌后机器才会移动。Claude 无法绕过这一机制——令牌由服务端生成并验证。

---

要求

• Universal GCode Sender 2.x（winder.github.io/ugs_website）
• 已安装并启用 UGS Pendant 插件（工具 → 插件 → 已安装）
• Pendant 正在 http://localhost:8080 上运行（默认值）
• Python 3.11+

---

安装

通过 pip 安装

pip install ugs-mcp

从源代码安装

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

---

Claude Code 配置

claude mcp add ugs-cnc ugs-mcp

也可以从源代码运行（不通过 pip install 安装）：

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

---

Claude Desktop 配置

在 ~/Library/Application Support/Claude/claude_desktop_config.json 中：

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

也可以从源代码运行：

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

---

配置

环境变量（均为可选）：

变量	默认值	描述
UGS_HOST	localhost	UGS Pendant 主机
UGS_PORT	8080	UGS Pendant 端口
MACROS_DIR	ugs_mcp/macros/	保存的 G-code 宏的目录
RAPID_SPEED_MM_MIN	5000	返回零点时使用的快速移动速度

复制 .env.example 到 .env 进行自定义。

---

令牌系统

所有运动工具都必须经过两步确认：

步骤 1 — 不带令牌调用工具。Claude 会显示操作预览（轴、距离、移动后的位置、安全警告）以及类似 [A3F8B2C1] 的令牌。

步骤 2 — 阅读预览。如果你同意，就把令牌告诉 Claude。Claude 会再次调用工具，并传入 confirmation_token="A3F8B2C1"。机器随即移动。

令牌由服务端通过 uuid4() 生成，有效期为 2 分钟，且只能使用一次。Claude 无法预测、伪造或重复使用令牌。只有你输入令牌，机器才会移动。

---

工具

完整的工具参考（含参数、示例和典型工作流），请参阅 USER_GUIDE.md。

类别	工具
连接	ugs_connect、ugs_disconnect、ugs_troubleshoot_connection
状态	ugs_get_status、ugs_get_job_status
作业	ugs_run_file、ugs_pause_job、ugs_cancel_job
运动	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

---

测试环境

• SainSmart Genmitsu 3018 Pro（GRBL）
• 带 Pendant 插件的 UGS 2.x
• macOS / Python 3.11

可能适用于任何基于 GRBL 的机器。TinyG/FluidNC/Smoothieware 未经测试。

---

许可证

MIT — 请参阅 LICENSE。

不提供任何担保。不承担任何责任。请阅读 SAFETY.md。