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 を英語に翻訳し、安全性を確認し、サイクル時間を見積もり、ツール一覧を表示します

すべての移動コマンドは、2 段階のトークンプロトコルを使用します。Claude がトークンを生成してあなたに表示し、あなたがそのトークンを読み返した場合にのみマシンが動きます。Claude はこれを回避できません。トークンはサーバー側で生成および検証されます。

---

要件

• Universal GCode Sender 2.x（winder.github.io/ugs_website）
• UGS Pendant プラグインがインストールされ、有効になっていること（Tools → Plugins → Installed）
• 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 にコピーしてカスタマイズしてください。

---

トークンシステム

すべての移動ツールでは、必須の 2 段階確認を使用します。

ステップ 1 — トークンを指定せずにツールを呼び出します。Claude がプレビュー（軸、距離、 移動後の位置、安全上の警告）と [A3F8B2C1] のようなトークンを表示します。

ステップ 2 — プレビューを読みます。同意する場合は、Claude にトークンを伝えます。Claude は confirmation_token="A3F8B2C1" を指定して再度ツールを呼び出し、マシンが動きます。

トークンは uuid4() を使ってサーバー側で生成され、2 分で期限切れになり、1 回のみ使用できます。 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コード	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）
• ペンダントプラグインを使用した UGS 2.x
• macOS / Python 3.11

GRBL ベースのマシンであれば、動作する可能性が高いです。TinyG/FluidNC/Smoothieware ではテストされていません。

---

ライセンス

MIT — LICENSE を参照してください。

保証はありません。責任は負いません。SAFETY.md をお読みください。