Gearotons M17 Servomotor

servomotor-mcp

通过自然语言驱动开源 Gearotons M17 伺服电机。

一个 MCP 服务，可将 M17——一款集成式闭环 NEMA-17 RS-485 伺服电机——提供给 Claude Desktop、Claude Code 或任何 MCP 客户端。只需开口询问，即可控制真实电机：

“找到我的电机，让工作台上的那台慢慢转两整圈。”

无需硬编码：服务会发现你的串行端口，自动检测总线上的电机（使用固件的“Detect devices”命令），并提供完整的固件命令集——servomotor 库目录中的每条命令都会自动成为 MCP 工具（截至库版本 0.10.0，共有 48 条命令），此外还提供一些适用于日常操作的高级工具。它自带模拟后端，因此无需任何硬件即可体验全部功能。

▶ 50 秒视频：真实电机与本次会话的并列展示 — 于 2026-09-09 在一台工作台上的 M17 上录制；上方每一行都来自会话日志。

分步教程（从开箱到“与它对话”，约需 20 分钟）：通过 Claude Code 与伺服电机对话，发布于 Hackster。

首款提供官方 MCP 服务的伺服电机。开放硬件、开放固件、开放软件——如今还拥有开放的、原生支持 AI 的控制接口。

---

快速开始（无需硬件，约 2 分钟）

# Run the server directly with uv (recommended). This runs the SIMULATOR —
# for real motors see "Drive real motors" below:
uvx --from servomotor-mcp servomotor-mcp

# or install it:
pip install servomotor-mcp
servomotor-mcp

然后将其添加到 Claude Desktop——将 examples/claude_desktop_config.json 中的代码块复制到 你的 claude_desktop_config.json，重启 Claude Desktop，然后询问： “你能看到哪些串行端口？连接并找到我的电机。” 参见 examples/demo_prompts.md 获取脚本化演示。

驱动真实电机

将 M17（或一串菊花链连接的 M17）接入 USB↔RS-485 适配器，并安装 [serial] 附加组件——就这么简单，无需配置：

pip install 'servomotor-mcp[serial]'   # pulls in the Gearotons servomotor library
servomotor-mcp

安装 servomotor 库后，服务会自动使用真实串行后端。若未安装，该服务会运行模拟器并说明这一点：list_serial_ports 和 connect 会返回 notice 字段，并向 stderr 输出警告。使用 uv 时，运行 uvx --from 'servomotor-mcp[serial]' servomotor-mcp。在会话中，模型随后会：

1. list_serial_ports — 列出机器上的端口（macOS /dev/cu.*、 Windows COM*、Linux /dev/ttyUSB*），并标记 USB 串行适配器；
2. connect — 以 230400 波特率打开你（或模型）选择的端口；
3. 自动检测总线上的每台电机（唯一 ID + 别名）——无需编写地址映射；
4. 驱动电机。如果有多个适配器，请用通俗易懂的语言告诉它使用哪一个。

工具

高级功能（发现 + 日常运动）：

工具	功能
list_serial_ports	枚举串口，并显示 USB 元数据（首先调用）。
connect / disconnect	打开端口并自动检测总线上的电机。
detect_devices	重新扫描总线（会重启总线上的电机）。
list_motors	列出检测到的电机及其实时位置、电压、温度和状态。
move_to / move_relative	按角度进行绝对 / 相对移动；等待移动完成。
stop	紧急停止一个或所有电机。
get_motor_status	获取单个电机的状态快照，并将致命错误解码为通俗易懂的描述。
run_sequence	编排多个步骤（例如“画一个正方形”），包括原始命令步骤。

此外，每个固件命令都对应一个工具，由库的命令目录生成： enable_mosfets、go_to_position、move_with_velocity、move_with_acceleration、 multimove、homing、zero_position、get_position、get_temperature、 set_device_alias、set_pid_constants、system_reset、vibrate、ping，等等—— 电机能执行的操作，模型就能执行。电机可通过别名编号、16 位十六进制唯一 ID 或 "all"（广播）寻址。数值使用易懂的单位（度、秒、度/秒、伏特、°C）；服务会将其转换为固件单位。

工作原理

natural language → Claude → MCP tool calls → this server → RS-485 → M17 motors

该服务是 Gearotons servomotor Python 库之上的轻量封装。该库由数据驱动—— motor_commands.json 定义了每个固件命令——服务会将同一命令目录转换为 MCP 工具，因此库中的新命令会自动出现。工具调用会直接转发至硬件——不进行软件限幅；支持完整的多圈行程和任意速度。电机自身的固件保护（过流 / 过压 / 过温）仍然有效。同一套工具也可通过模拟后端运行 （GEAROTONS_MOTOR_BACKEND=mock），用于开发和 CI。

环境变量（均为可选）：

• GEAROTONS_MOTOR_BACKEND — auto（默认：安装了 servomotor 库时使用串口，否则使用模拟后端）、serial 或 mock。
• GEAROTONS_SERIAL_PORT — 模型未指定端口时，connect 使用的默认端口。
• GEAROTONS_DEFAULT_SPEED_DPS — move_to / move_relative 的默认速度（180）。

开发 / 测试

pip install -e '.[dev]'
GEAROTONS_MOTOR_BACKEND=mock pytest     # catalog + mock-bus + server-tool tests

hardware_tests/ 包含用于通过台架电机端到端测试真实串口路径的脚本（端口扫描、完整命令套件、stdio MCP 会话）。

状态

• ✅ 完整的固件命令集（48 条命令）、串口发现、总线自动检测——已通过真实 stdio MCP 会话和 uvx 在实体 M17 上验证（固件版本 0.15.3.0），并使用全部四个测试适配器进行测试（仅在电机实际连接的位置检测到电机）。
• ✅ 模拟后端 + 39 个单元测试，无需硬件。
• ✅ 通过 pyserial 枚举实现跨平台端口处理（macOS / Windows / Linux）。

许可证

MIT。M17 的硬件、固件和软件均为开源—— 参见 github.com/tomrodinger/servomotor。