Skip to main content
Glama
roboguide-mcp

roboguide-mcp

by qiuyekai
README.md
# roboguide-mcp

An [MCP](https://modelcontextprotocol.io) server that lets **any AI assistant** work with **FANUC ROBOGUIDE**:
write and load TP programs, run them on the virtual controller, read registers / I/O / alarms / positions,
command motion, and operate the ROBOGUIDE window itself.

It works with every MCP client (Claude, ChatGPT, Gemini CLI, Cursor, VS Code Copilot, Cline, Codex CLI, ...)
because it uses only plain MCP tools with simple parameters.

[中文说明见下方](#中文说明)

> **Status: alpha, not yet validated on ROBOGUIDE.** The protocol code follows FANUC's RMI manual and
> open-source projects written against real controllers, and the whole tool set passes an automated test suite
> against a *simulated* controller. It has **not** yet been run against a real ROBOGUIDE installation or a
> real robot. See [What is verified](#what-is-verified). Reports from real setups are very welcome.

## Install

Requirements: Python 3.10+ and, for anything useful, a PC running ROBOGUIDE (Windows).

```
pip install https://github.com/qiuyekai/roboguide-mcp/archive/refs/heads/main.zip
```

Check the installation (prints the configuration and the tool list, then exits):

```
python -m roboguide_mcp --check
```

### Instructions for AI agents installing this server

1. Run the `pip install` command above with the Python the user wants to use.
2. Run `python -m roboguide_mcp --check`; it must print `roboguide-mcp ... OK`.
3. Register the server in the user's MCP client using the matching snippet below. Use the absolute path of
   that Python as `command` if `python` is not on PATH.
4. Leave every `ROBOGUIDE_MCP_ALLOW_*` switch **off** unless the user explicitly asks for it. Tell the user
   which switches exist and let them decide.
5. After the client restarts, call the `server_status` tool and then `probe_controller`.

## Connect it to your AI client

**Claude Desktop, Cursor, Cline, Windsurf, Gemini CLI** (`mcpServers` JSON):

```json
{
  "mcpServers": {
    "roboguide": {
      "command": "python",
      "args": ["-m", "roboguide_mcp"],
      "env": {
        "ROBOGUIDE_MCP_ALLOW_WRITES": "0",
        "ROBOGUIDE_MCP_ALLOW_MOTION": "0",
        "ROBOGUIDE_MCP_ALLOW_GUI": "0"
      }
    }
  }
}
```

**Claude Code**

```
claude mcp add roboguide -- python -m roboguide_mcp
```

**VS Code (GitHub Copilot)** - `.vscode/mcp.json`:

```json
{ "servers": { "roboguide": { "type": "stdio", "command": "python", "args": ["-m", "roboguide_mcp"] } } }
```

**Codex CLI** - `~/.codex/config.toml`:

```toml
[mcp_servers.roboguide]
command = "python"
args = ["-m", "roboguide_mcp"]
```

**Web / remote clients (Streamable HTTP)** - start the server on the ROBOGUIDE PC, then give the client
the URL `http://<pc>:8765/mcp`:

```
python -m roboguide_mcp --transport http --host 127.0.0.1 --port 8765
```

The HTTP transport has no authentication. Keep it on `127.0.0.1`, or put it behind a tunnel / reverse proxy
that adds authentication.

## Safety switches

The server is **read-only by default**. A human enables riskier tool groups through environment variables;
a blocked tool tells the AI which switch is missing. The AI cannot change these itself.

| Variable | Unlocks |
|---|---|
| `ROBOGUIDE_MCP_ALLOW_WRITES=1` | uploading / deleting files, writing registers, I/O and variables |
| `ROBOGUIDE_MCP_ALLOW_MOTION=1` | running / aborting programs, fault reset, RMI motion |
| `ROBOGUIDE_MCP_ALLOW_GUI=1` | clicking and typing in the ROBOGUIDE window |
| `ROBOGUIDE_MCP_ALLOW_REAL_ROBOT=1` | writes and motion on controllers that are **not** on `127.0.0.1` |

Without `ALLOW_REAL_ROBOT`, writes and motion are refused for any non-loopback address, so the server cannot
move a real robot by accident. **A real robot can injure people. Only enable that switch if you are qualified
to operate the robot and accept the risk.**

## Other settings

| Variable | Default | Meaning |
|---|---|---|
| `ROBOGUIDE_MCP_HOST` | `127.0.0.1` | controller address (ROBOGUIDE virtual robots listen on loopback) |
| `ROBOGUIDE_MCP_HTTP_PORT` | `80` | controller web server port |
| `ROBOGUIDE_MCP_FTP_PORT` | `21` | controller FTP port |
| `ROBOGUIDE_MCP_RMI_PORT` | `16001` | Remote Motion Interface port |
| `ROBOGUIDE_MCP_FTP_USER` / `_FTP_PASSWORD` | `anonymous` / `guest` | FTP login, if the controller requires one |
| `ROBOGUIDE_MCP_TIMEOUT` | `5` | network timeout in seconds |
| `ROBOGUIDE_MCP_WORKCELL_DIRS` | *(none)* | extra folders containing workcells, separated by `;` |
| `ROBOGUIDE_MCP_GUI_WINDOW` | ROBOGUIDE product names | regex for the window titles / process names the GUI tools may touch |
| `ROBOGUIDE_MCP_TOOLSETS` | `core,gui,rmi` | which tool groups to expose (fewer tools help smaller models) |

The second and later robots of a workcell use different ports. ROBOGUIDE writes them to
`<workcell>\Robot_N\services.txt`; the `find_workcells` tool shows that file, and `set_target` switches robot.

## Tools

**Discovery** - `server_status`, `probe_controller`, `set_target`, `find_workcells`

**Programs and files** - `list_files`, `read_file`, `check_ls_program`, `ls_program_template`,
`upload_program`*, `upload_file`*, `delete_file`*

**Data** - `read_registers`, `write_register`*, `read_position_registers`, `read_io`, `write_io`*,
`read_alarms`, `read_current_position`, `read_frames`, `read_variable`, `write_variable`*,
`set_speed_override`*

**Execution** - `run_program`**, `abort_programs`**, `reset_alarms`**, `kcl_command`* **

**Direct motion (RMI, option R912)** - `rmi_connect`**, `rmi_status`, `rmi_read_position`,
`rmi_move_linear`**, `rmi_move_joint`**, `rmi_call_program`**, `rmi_write_position_register`*,
`rmi_disconnect`

**ROBOGUIDE window** - `gui_list_windows`, `gui_dump_controls`, `gui_screenshot`, `gui_click`***,
`gui_invoke`***, `gui_set_text`***, `gui_send_keys`***

\* needs `ALLOW_WRITES`  \*\* needs `ALLOW_MOTION`  \*\*\* needs `ALLOW_GUI`

### How it stays independent of ROBOGUIDE version and UI language

* **Controller tools** talk to the virtual controller over its own network services (FTP, web server, RMI),
  not through the ROBOGUIDE user interface. Those services and their text formats are the same on R-30iA,
  R-30iB, R-30iB Plus and R-50iA controllers and do not depend on the UI language. `probe_controller` detects
  which channels a given controller offers, and each tool falls back to another channel when one is missing.
* **GUI tools** contain no hard-coded menu names or click sequences. `gui_dump_controls` returns the window's
  control tree in whatever language ROBOGUIDE is running; the AI reads it and acts on positional `ref`s.
  This is the only way to edit the 3D scene (add fixtures and parts, set object coordinates, start a
  simulation run), because ROBOGUIDE has no public API for it.
* Comments in Japanese or Chinese encodings (Shift-JIS, GBK) are detected automatically. The two encodings
  overlap, so for short texts the guess can be wrong; set `ROBOGUIDE_MCP_TEXT_ENCODING=gbk` (or `shift_jis`)
  to force one.

### Controller-side setup

| To use | The (virtual) controller needs |
|---|---|
| reading files and diagnostics | nothing extra (FTP and web server are standard) |
| `upload_program` with `.LS` text | the ASCII program loader option (normally present in ROBOGUIDE) |
| `write_register`, `write_io`, `write_variable`, `run_program`, `read_current_position` | `SETUP > Host Comm > HTTP`: set **KCL** and **KAREL** to *Unlock* |
| `rmi_*` | option **R912 Remote Motion Interface**, controller in AUTO, teach pendant disabled |

## What is verified

| Area | State |
|---|---|
| MCP server, tool registration, stdio and HTTP transports | tested with the official MCP Python SDK (2.x; 1.9+ supported by a compatibility shim) |
| Safety switches | tested: every write / motion / GUI tool is refused by default |
| FTP, MD: file parsing, KCL, KAREL ComSet, COMET | tested against a **simulated** controller that replays text captured from real controllers by the [go-fanuc](https://github.com/onerobotics/go-fanuc) and [dominh](https://github.com/gavanderhoorn/dominh) projects |
| RMI motion | tested against a **simulated** endpoint written from FANUC manual B-84184EN |
| GUI tools | tested on ordinary Windows applications; **not** tested on ROBOGUIDE, whose controls may be only partly visible to UI Automation |
| Real ROBOGUIDE / real controller | **not tested yet** |

Known uncertainties: `run_program` uses the KCL `RUN` command, whose behaviour over HTTP differs between
controller configurations; ports of the 2nd+ virtual robot must be taken from `services.txt`; COMET is an
undocumented FANUC interface and can change between versions (the tools fall back when it is missing).

## Limitations

* The 3D scene can only be changed through the GUI tools; `.frw` workcell files are never edited
  (ROBOGUIDE rejects modified files).
* GUI tools need ROBOGUIDE running in an interactive desktop session on the same PC as this server.
* One RMI session per controller; RMI is not a real-time streaming interface.

## Development

```
git clone https://github.com/qiuyekai/roboguide-mcp
cd roboguide-mcp
pip install -e ".[dev]"
pytest
python tests/mock_controller.py   # a simulated controller to try the tools without ROBOGUIDE
```

## Disclaimer

Not affiliated with or endorsed by FANUC. FANUC and ROBOGUIDE are trademarks of FANUC CORPORATION.
This software is provided as is, without warranty; you are responsible for how it is used, especially with
real equipment.

## License

MIT

---

## 中文说明

`roboguide-mcp` 是一个 MCP 服务器,让**任何支持 MCP 的 AI**(Claude、ChatGPT、Gemini CLI、Cursor、
VS Code Copilot、Cline、Codex CLI 等)都能操作 **FANUC ROBOGUIDE**:编写并下载 TP 程序、在虚拟控制器上运行、
读取寄存器 / I/O / 报警 / 位置、发送运动指令,以及操作 ROBOGUIDE 窗口。

> **当前状态:alpha,尚未在真实 ROBOGUIDE 上验证。** 协议实现依据 FANUC 的 RMI 手册和针对真机编写的开源项目,
> 全部工具已通过针对**模拟控制器**的自动化测试,但还没有在真实的 ROBOGUIDE 或真机上运行过。

### 安装

```
pip install https://github.com/qiuyekai/roboguide-mcp/archive/refs/heads/main.zip
python -m roboguide_mcp --check
```

然后把上文 "Connect it to your AI client" 中对应的配置加入你的 AI 客户端。也可以直接把本仓库链接发给 AI,
让它按 "Instructions for AI agents installing this server" 一节安装。

### 安全开关

服务器**默认只读**。需要由人在环境变量里打开对应开关,AI 自己无法修改:

| 环境变量 | 作用 |
|---|---|
| `ROBOGUIDE_MCP_ALLOW_WRITES=1` | 允许上传/删除文件,写寄存器、I/O、系统变量 |
| `ROBOGUIDE_MCP_ALLOW_MOTION=1` | 允许运行/中止程序、复位报警、RMI 运动 |
| `ROBOGUIDE_MCP_ALLOW_GUI=1` | 允许在 ROBOGUIDE 窗口里点击和输入 |
| `ROBOGUIDE_MCP_ALLOW_REAL_ROBOT=1` | 允许对非本机(非 127.0.0.1)的控制器写入和运动 |

不打开最后一个开关时,服务器拒绝对任何非本机地址执行写入和运动,因此不会误动真机。
**真实机器人可能造成人身伤害,只有具备操作资质并接受风险时才应打开该开关。**

### 如何做到不依赖 ROBOGUIDE 版本和界面语言

* **控制器类工具**通过虚拟控制器自身的网络服务(FTP、网页服务、RMI)工作,不经过 ROBOGUIDE 界面,
  这些服务在各代控制器上一致,也与界面语言无关。`probe_controller` 会探测当前控制器支持哪些通道,
  某个通道不可用时工具会自动换用其他通道。
* **界面类工具**不写死任何菜单名称或点击步骤。`gui_dump_controls` 返回当前窗口的控件树(界面是什么语言就是
  什么语言),由 AI 阅读后按位置编号操作。这是编辑 3D 场景(添加夹具和工件、设置坐标、启动仿真)的唯一途径,
  因为 ROBOGUIDE 没有公开的场景接口。

### 控制器侧需要的设置

* 读取文件和诊断信息:无需额外设置。
* 写寄存器 / I/O / 变量、运行程序、读当前位置:在示教器 `SETUP > Host Comm > HTTP` 中把 **KCL** 和
  **KAREL** 设为 *Unlock*。
* `rmi_*` 工具:需要 **R912 Remote Motion Interface** 选项,控制器处于 AUTO 且示教器未使能。

### 已知限制

* 3D 场景只能通过界面类工具修改;不会编辑 `.frw` 工作站文件(ROBOGUIDE 会拒绝被修改过的文件)。
* 界面类工具要求 ROBOGUIDE 与本服务器运行在同一台电脑的桌面会话中,且尚未在 ROBOGUIDE 上实测。
* 本项目与 FANUC 无关联,未获其认可。