roboguide-mcp
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
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.zipCheck the installation (prints the configuration and the tool list, then exits):
python -m roboguide_mcp --checkInstructions for AI agents installing this server
Run the
pip installcommand above with the Python the user wants to use.Run
python -m roboguide_mcp --check; it must printroboguide-mcp ... OK.Register the server in the user's MCP client using the matching snippet below. Use the absolute path of that Python as
commandifpythonis not on PATH.Leave every
ROBOGUIDE_MCP_ALLOW_*switch off unless the user explicitly asks for it. Tell the user which switches exist and let them decide.After the client restarts, call the
server_statustool and thenprobe_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_mcpVS 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 8765The 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 |
| uploading / deleting files, writing registers, I/O and variables |
| running / aborting programs, fault reset, RMI motion |
| clicking and typing in the ROBOGUIDE window |
| writes and motion on controllers that are not on |
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 |
|
| controller address (ROBOGUIDE virtual robots listen on loopback) |
|
| controller web server port |
|
| controller FTP port |
|
| Remote Motion Interface port |
|
| FTP login, if the controller requires one |
|
| network timeout in seconds |
| (none) | extra folders containing workcells, separated by |
| ROBOGUIDE product names | regex for the window titles / process names the GUI tools may touch |
|
| 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_controllerdetects 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_controlsreturns the window's control tree in whatever language ROBOGUIDE is running; the AI reads it and acts on positionalrefs. 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(orshift_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) |
| the ASCII program loader option (normally present in ROBOGUIDE) |
|
|
| 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;
.frwworkcell 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 ROBOGUIDEDisclaimer
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 自己无法修改:
环境变量 | 作用 |
| 允许上传/删除文件,写寄存器、I/O、系统变量 |
| 允许运行/中止程序、复位报警、RMI 运动 |
| 允许在 ROBOGUIDE 窗口里点击和输入 |
| 允许对非本机(非 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…
This server cannot be deployed
Maintenance
Related MCP Connectors
Protocol-native energy infrastructure orchestration for AI data centers. Provides 46 MCP tools across 8 grid protocols (IEC-61850, DNP3, Modbus, OCPP, OpenADR, IEEE 2030.5, IEC 60870-5-104, ICCP) with 5 core API primitives: connect, dispatch, settle, comply, and intel. Enables AI agents to programmatically interact with substations, grid interfaces, and energy assets for real-time workload-grid coordination.
Connect AI assistants to your approved computer for files, commands, browser and desktop tasks.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
Trading MCP server for AI agents, with live market data, account reads and controlled execution.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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.6GPL 3.0
- AlicenseNot gradedqualityBmaintenanceEnables 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 npmMIT
- FlicenseNot gradedqualityDmaintenanceEnables 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.-
- AlicenseNot gradedqualityBmaintenanceEnables 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