Skip to main content
Glama
roboguide-mcp

roboguide-mcp

by qiuyekai

roboguide-mcp

An MCP 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. 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.

Related MCP server: rvn

Connect it to your AI client

Claude Desktop, Cursor, Cline, Windsurf, Gemini CLI (mcpServers 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:

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

Codex CLI - ~/.codex/config.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 refs. 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 and 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 无关联,未获其认可。

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to control Universal Robots through real-time connection management, status monitoring, and precise joint/linear motion control. Provides safe robot operation with built-in collision detection and simulation mode for development without physical hardware.
      6
      GPL 3.0
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables AI clients to securely control and interact with a local Windows machine through 218 configurable tools for files, Git, processes, Windows UI, browser automation, WSL, Office, recovery, skills, and child MCP servers.
      11 npm
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables agents to safely drive a simulated Franka Panda pick-and-place cell through MCP tools, with gated motion, emergency stop, structured errors, and audit logging.
      -
    • A
      license
      Not graded
      quality
      B
      maintenance
      Enables MCP-capable AI assistants to control a Windows computer through GUI automation, file and process operations, PowerShell commands, durable background jobs, and binary file transfer with downloadable exports.
      MIT