Robot NXT Control MCP

适用于通过 USB/WinUSB 连接到 Windows 11 的兼容可编程积木硬件的本地 MCP 服务器。

兼容性与商标

本项目是独立项目，与 LEGO Group 无关联，未受其赞助，也未获得其认可。LEGO、MINDSTORMS 和 NXT 是 LEGO Group 的商标。它们在本文档中仅用于标识兼容的硬件、软件、协议和第三方依赖；它们不属于本项目的名称、服务器标识符或插件标识符。

从早期版本迁移

旧的插件和 MCP 服务器标识符已替换为 robot-nxt-control，可执行文件现在命名为 robot-nxt-control-mcp、robot-nxt-control-mcp-stdio 和 robot-nxt-control-mcp-http。拉取此更改后重新安装可编辑包，并将之前的 MCP 配置条目替换为下面的示例。

Related MCP server: KentraBOT MCP Server

在 Claude Desktop 或 Codex 桌面版中安装（Windows）

首先完成 Windows 安装。这些桌面应用会自行启动 MCP 服务器，因此不要手动运行 robot-nxt-control-mcp-stdio.exe。以下示例假设本仓库位于 C:\Users\lukas\workspace\NXT-MCP；如果你的检出位置在其他地方，请替换所有路径中的这一部分。

Claude Desktop

1. 完全退出 Claude Desktop（包括其托盘图标）。

2. 打开 %APPDATA%\Claude\claude_desktop_config.json。如果文件不存在，请创建它。如果它已有 mcpServers 对象，只需添加下面的 robot-nxt-control 条目。

3. 保存文件并重新启动 Claude Desktop。服务器应出现在 设置 → 开发者 → MCP 服务器 中。

{
  "mcpServers": {
    "robot-nxt-control": {
      "command": "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe",
      "cwd": "C:\\Users\\lukas\\workspace\\NXT-MCP"
    }
  }
}

相同的现成配置位于 packaging/claude-desktop/mcp.json。

Codex 桌面版

Codex 桌面宿主和 Codex CLI 使用 %USERPROFILE%\.codex\config.toml 中的共享 MCP 配置。添加以下块（或运行下面的等效 codex mcp add 命令），然后重新启动 Codex 应用：

[mcp_servers.robot-nxt-control]
command = "C:\\Users\\lukas\\workspace\\NXT-MCP\\.venv\\Scripts\\robot-nxt-control-mcp-stdio.exe"
cwd = "C:\\Users\\lukas\\workspace\\NXT-MCP"
startup_timeout_sec = 10
tool_timeout_sec = 120

PowerShell 替代方案：

codex mcp add robot-nxt-control -- C:\Users\lukas\workspace\NXT-MCP\.venv\Scripts\robot-nxt-control-mcp-stdio.exe
codex mcp list

对于 ChatGPT 桌面版 MCP UI：设置 → MCP 服务器 → 添加服务器，选择 STDIO，输入 robot-nxt-control，使用与命令相同的可执行文件，保存，然后重新启动应用。本地 Codex 客户端同时支持 STDIO 和 Streamable HTTP，并共享此 MCP 配置。OpenAI 官方 MCP 文档

首次检查

打开一个新聊天，请求 nxt_info。如果无法连接，请先用 ./.venv/Scripts/nxt-test.exe --log-level=debug 确认机器人能正常工作；然后验证所有配置的路径都存在，并且 NXT 已开机。移动工具控制真实硬件：从 nxt_info 或 query_all_state 开始，然后使用低功率和有界的移动命令。

MCP 传输、宿主与验证

同一个 create_server() 工厂为两种传输提供支持。robot-nxt-control-mcp-stdio 是面向 Claude Desktop、Claude Code、Codex CLI、Codex 桌面版和本地 Codex 插件的本地进程传输。它仅将协议流量写入 stdout。

使用提供的 JSON 作为起始配置，并在移动检出位置后替换绝对工作区路径：

• Claude Desktop：packaging/claude-desktop/mcp.json

• Claude Code 插件：packaging/claude-code/

• Codex 本地插件：C:\Users\lukas\plugins\robot-nxt-control（在个人市场中创建）

如需进行协议测试，请在环回地址上启动 Streamable HTTP：

.\.venv\Scripts\robot-nxt-control-mcp-http.exe --port 8000
npx @modelcontextprotocol/inspector --cli http://127.0.0.1:8000/mcp --method tools/list
npx @modelcontextprotocol/conformance server --url http://127.0.0.1:8000/mcp --suite active

使用 .\.venv\Scripts\python.exe -m pytest 运行仓库检查。除了控制器和行为测试外，它们还包括进程内 MCP 协商、tools/list、注解和 tools/call 测试。conformance-baseline.yml 仅记录需要此专注型硬件服务器未通告的可选 MCP 功能的通用场景；每个条目都是一条燃尽断言，因此运行器会标记过时的条目。

robot-nxt-control-mcp-http 默认绑定到 127.0.0.1，并且除非显式设置 NXT_MCP_ALLOW_REMOTE=true，否则拒绝非环回绑定。云客户端无法直接访问 USB NXT：请在与机器人相邻的位置运行此服务器，并在 Streamable HTTP 端点前放置带有 OAuth/令牌验证、授权、审计日志和网络限制的生产级 HTTPS 反向代理。切勿仅凭环境变量覆盖就将 USB 控制端点公开暴露。

有关模块设计、MCP 与行为执行流程、USB 协议栈、安全模型和 Mermaid 图，请参阅 ARCHITECTURE.md。

Windows 11 安装

使用 Python 3.11 x64。在 PowerShell 中：

py -3.11 -m venv .venv
.\.venv\Scripts\python.exe -m pip install --upgrade pip
.\.venv\Scripts\python.exe -m pip install -e ".[test]"

1. 使用 Zadig 安装 NXT 设备驱动程序

打开 NXT 并通过 USB 连接。在 PowerShell 中，确认 Windows 能看到普通模式设备：

Get-PnpDevice -PresentOnly |
  Where-Object InstanceId -match 'VID_0694&PID_0002' |
  Format-List Status,FriendlyName,InstanceId,Problem

硬件 ID 必须包含 USB\VID_0694&PID_0002。如果 Problem 为 CM_PROB_FAILED_INSTALL，或设备管理器显示 Code 28，则说明缺少驱动程序。

1. 仅从 https://zadig.akeo.ie/ 下载 Zadig。

2. 以管理员身份运行 Zadig。

3. 选择 选项 > 列出所有设备。

4. 选择 USB ID 恰好为 0694:0002 的条目。请使用 ID，而不仅仅是显示的设备名称。

5. 在驱动程序选择器中选择 WinUSB。

6. 单击 安装驱动程序 或 替换驱动程序。

7. 断开并重新连接 NXT，保持其开机状态。

不要选择 03EB:6124；那是 NXT 引导加载程序/固件更新模式。不要替换任何无关 USB 设备的驱动程序。安装 WinUSB 可能会阻止旧的 LEGO NXT-G 软件与主控通信，直到恢复其 LEGO/Fantom 驱动程序。

2. 为 PyUSB 安装 x64 版 libusb 运行时

WinUSB 是 Windows 设备驱动程序。PyUSB 另外需要用户空间的 libusb-1.0.dll。本仓库包含一个辅助程序，它下载官方 libusb 1.0.30 归档，验证其 SHA-256，并将 VS2022 x64 DLL 安装到此环境的 python.exe 旁边：

.\scripts\install-libusb-runtime.ps1

该辅助程序需要 7z.exe 位于 PATH 中。若要手动安装，请从官方 libusb GitHub 版本下载 libusb-1.0.30.7z，解压 VS2022\MS64\dll\libusb-1.0.dll，并将其复制到 .venv\Scripts\libusb-1.0.dll。不要将 MS32 DLL 用于 64 位 Python。

独立验证运行时：

$env:PATH = "$PWD\.venv\Scripts;$env:PATH"
.\.venv\Scripts\python.exe -c "import usb.backend.libusb1 as b; assert b.get_backend() is not None; print('libusb OK')"

MCP 服务器会自动将安装在其虚拟环境 Python 旁边的 DLL 添加到其自身的搜索路径。nxt-test.exe 是外部 NXT-Python 命令，因此请先运行上面的 $env:PATH 行，或者在使用它之前激活虚拟环境。

3. 测试主控

在 MCP 之前验证硬件：

.\.venv\Scripts\nxt-test.exe --log-level=debug

成功的测试会打印主控名称、电池电量、协议版本和固件版本。如果仍然报告找不到主控，请重新检查设备管理器中的 0694:0002 设备，并确认其驱动程序为 WinUSB。

固件

当 NXT 正常启动且 Windows 显示 VID 0694 / PID 0002 时，无需安装或更新固件。MCP 服务器使用标准 NXT 直接命令，并通过 nxt_info 报告已安装的固件和协议版本。

仅当主控无法正常启动且 Windows 显示 VID 03EB / PID 6124（即 Atmel SAM-BA 固件更新模式）时，才执行固件恢复。恢复会擦除并重写主控固件，不属于正常的 MCP 设置范围：

1. 不要针对 03EB:6124 安装常规的 NXT WinUSB 规则。

2. 恢复/使用原始 LEGO MINDSTORMS NXT 软件所需的固件更新驱动程序。

3. 在该软件中，使用 工具 > 更新 NXT 固件，并选用官方 NXT 固件镜像。

4. 恢复后，重新为主控断电再上电。它必须恢复为 0694:0002；如有必要，再次为该普通模式设备安装 WinUSB。

NXT-Python 刻意不提供固件刷写功能。不要仅仅为了排查 NoBackendError、Code 28 或 MCP 连接失败而调用固件启动模式或尝试更新固件。

然后打开 MCP Inspector：

.\.venv\Scripts\mcp.exe dev src\nxt_mcp\server.py

对于本地 MCP 宿主，配置一个 stdio 服务器，命令为 .venv\Scripts\robot-nxt-control-mcp.exe，工作目录为仓库目录。

在启动服务器之前声明连接到主控的传感器，以便整机快照能立即返回类型化的读数：

$env:NXT_SENSOR_MAP = "1:touch,2:light,4:ultrasonic"
.\.venv\Scripts\robot-nxt-control-mcp.exe

调用 read_sensor 或传感器驱动的电机命令也会记住该端口类型，以便用于后续快照。

高级工具

• move_motor_relative(port="C", power=40, degrees=2000) 让 C 正向移动 2000 编码器度。使用负功率可反向移动。适配器使用紧密的 USB 编码器循环，因为 NXT-Python 的标准 turn() 循环对小幅移动的轮询速度太慢。对于约 45 度的移动，请使用较低的功率，例如 20。

• zero_motor_position(port="C") 将 C 的当前编码器位置定义为绝对 0。然后 move_motor_absolute(port="C", target_degrees=-90, power=20) 移动到 -90。绝对移动根据目标推导方向；其 power 是正值大小。

• motor_position(port="C") 报告绝对/程序相对编码器位置以及原始 tacho 计数器。

• run_motor(port="C", power=-30) 持续沿负方向运行，直到停止命令或有界行为将其停止。使用 regulated=true 时，power 是 NXT 调节速度设置，而不是校准的每秒度数（degrees-per-second）值。

• run_motors(ports=["B", "C"], powers=[30, -30]) 在一次 MCP 调用中启动一个电机组。stop_motors、move_motors_relative 和 move_motors_absolute 以相同方式作用于组。列表是按位置对应的：每个功率/度数值属于同一索引处的端口。

• run_motor_until_sensor(port="B", power=40, sensor_port=1, sensor_type="touch", condition="pressed") 运行 B，直到触摸传感器 S1 被按下。

• run_motors_until_sensor(ports=["B", "C"], powers=[40, 40], sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20) 驱动两个电机，直到障碍物距离至多 20 厘米，然后停止整个组。

• run_motor_until_sensor(port="B", power=40, sensor_port=4, sensor_type="ultrasonic", condition="lte", threshold=20) 运行 B，直到障碍物距离至多 20 厘米。

• query_all_state(format="text") 返回主控、所有电机端口和所有传感器端口的紧凑文本快照。使用 format="json" 获取结构化数据。

• cycle_motor_on_touch(port="C", touch_port=1, cycles=5) 正向运行直到 S1 被按下，然后反向运行直到其释放，重复五次，成功后发出蜂鸣声。每次按下和释放阶段都有自己的超时时间和编码器行程上限。

每个传感器驱动的运动都有超时时间和编码器行程限制。达到任一限制都会停止电机并返回 ok: false，附带原因。如果传感器或 USB 读取失败，电机也会停止。

扩展诊断、存储与遥测

• motor_state(port) 报告调节状态、运行状态、编码器计数和配置的输出状态。 drive_sync(left_port, right_port, power, turn_ratio=0) 使用 NXT 固件同步调节来实现差速驱动对；wait_motors(...) 具有截止时间，超时时会停止其端口。

• read_sensor_raw(port, sensor_type?)、wait_sensor(...) 和 sensor_stream(...) 提供有界诊断、带去抖的传感器等待和有限样本。

• 对于光、颜色和超声波传感器，先调用 zero_sensor_reference(port, sensor_type)，再调用 read_sensor_relative(port, sensor_type)。它返回相对于捕获零点的变化量加上绝对值。颜色传感器使用反射光强度（而不是离散的红/蓝等标签）来进行有意义的减法。

• log_start、log_status、log_stop 和 log_export 提供有界的主机端 CSV 遥测。 有效通道为 battery_mv、motor:A 至 motor:C，以及 sensor:1:touch（或其他受支持的传感器类型/端口）。

• list_files、read_file、write_file 和 delete_file 管理有界的 NXT 用户文件。 写入仅限于 .txt、.csv、.dat 和 .rso；声音播放使用 play_sound_file(name) 和 stop_sound()。

• mailbox_send / mailbox_receive 支持最多 58 个 UTF-8 字节的消息； i2c_transaction 是一种可选的低速操作，请求和响应负载限制为 16 字节。 set_brick_name 和 keep_alive 是受支持的管理性直接命令。

原版 NXT 直接命令协议无法在 NXT LCD 上绘制内容，也无法读取其按钮。 这些 NXT-G/ROBOTC 功能需要单独安装的 NXT 常驻桥接程序；本服务器有意不暴露这些功能。

电机定位语义

NXT 编码器计数是电机轴上的度数，而不是机器人航向的度数或线性毫米数。 如果需要物理单位，齿轮比、车轮周长和车轮打滑必须由机器人行为来处理。

绝对零点由 NXT 固件的程序相对旋转计数器保存。它不是归位传感器，也不持久： 为主机断电重启或启动/停止某个 .rxe 程序都会使该参考失效。在依赖绝对目标之前， 请以触摸传感器为基准进行归位，并再次调用 zero_motor_position。

组命令在同一个控制器锁内使用连续的 USB 数据包启动电机。它们避免了 MCP/LLM 往返偏差，并一起监控所有编码器，但它们不是硬实时或机械锁相的。对于两轮机器人来说，这适用于普通行驶；精确同步可能需要 NXT 常驻控制程序。

硬件报告限制

NXT 固件报告每个端口的已配置状态，但无法安全地判断空闲电机是否物理插入。 因此，整机查询报告所有 A/B/C 固件状态，而不是声称电机存在。已经由 read_sensor 或传感器驱动命令配置过的传感器端口会显示带类型的值；其他传感器端口显示其原始固件状态。查询原始状态不会重新配置端口，也不会短暂给硬件通电。

当某个 .rxe 程序正在控制相同端口时，不要使用直接的 MCP 电机命令。

通过 MCP 的 PC 端 Python 行为

原版 NXT 不能运行 Python。本服务器可以在 PC 上保存并运行受限的 Python 行为； 每个机器人操作仍然跨越控制器边界，因此脚本不会打开 USB、实例化 NXT-Python 传感器， 也不会实现自己的轮询循环。

示例行为：

def run(robot):
    robot.configure_sensor(1, "touch")

    for _ in range(5):
        robot.motor_until("C", 20, 1, "pressed")
        robot.motor_until("C", -20, 1, "released")

    robot.play_tone(440, 500)
    return "completed 5 touch cycles"

同一示例包含在 behaviors/touch_cycle.py 中。使用以下 MCP 工具：

validate_behavior(source)
submit_behavior(name, source)
list_behaviors()
get_behavior(name)
run_behavior(name, timeout_seconds=120)

脚本可见的 robot 接口包含：

configure_sensor(port, sensor_type)
read_sensor(port, sensor_type)
read_sensor_raw(port, sensor_type=None)
zero_sensor_reference(port, sensor_type)
read_sensor_relative(port, sensor_type)
wait_sensor(port, sensor_type, condition, ...)
sensor_stream(port, sensor_type, ...)
log_start(channels, interval_ms=100, duration_seconds=10)
log_status(job_id)
log_stop(job_id)
log_export(job_id)
motor_until(port, power, sensor_port, condition, sensor_type="touch", ...)
motor_for_ticks(port, power, ticks, ...)
motor_position(port)
zero_motor_position(port)
motor_to(port, target_degrees, power=20, ...)
run_motor(port, power, regulated=True)
drive_sync(left_port, right_port, power, turn_ratio=0)
wait_motors(ports, ...)
stop_motor(port, brake=False)
run_motors(ports, powers, regulated=True)
stop_motors(ports, brake=False)
motors_relative(ports, powers, degrees, ...)
motors_absolute(ports, powers, target_degrees, ...)
motors_until(ports, powers, sensor_port, condition, ...)
state(format="text")
play_tone(frequency_hz=440, duration_ms=500)
play_sound_file(name, loop=False)
stop_sound()
sleep(seconds)

导入、类、异常处理、访问私有属性，以及对文档化 robot 方法和基本内置函数之外内容的调用都会被拒绝。 脚本限制为 64 KiB，一次只能运行一个，run_behavior 接受 1–300 秒的截止时间。 当脚本完成或抛出异常时，所有电机都会停止。

此验证旨在防止意外访问 robot 接口之外的内容；它不是针对恶意代码的安全沙箱。 只向受信任的本地用户授予 MCP 访问权限。在启动服务器之前设置 NXT_BEHAVIOR_DIR， 以将行为存储到服务器工作目录下默认 behaviors 目录之外的其他位置。

如需使用 MCP stdio（而非直接导入控制器）的命令行演示：

.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py list
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py submit touch_cycle behaviors\touch_cycle.py
.\.venv\Scripts\python.exe scripts\mcp-behavior-client.py run touch_cycle --timeout 120

最后一条命令执行实际物理移动。客户端仅调用 MCP 工具；MCP 服务器加载行为并负责所有 NXT 通信。

在没有 NXT 主机的情况下测试

$env:PYTHONPATH = "src"
py -3.11 -m pytest