The full upstream README, mirrored here for reference. Install config, tool schemas, adoption signals, and an original overview live on the Gearotons M17 Servomotor listing page.
Drive open-source Gearotons M17 servomotors from natural language.
An MCP server that exposes the M17 — a NEMA-17 integrated, closed-loop, RS-485 servomotor — to Claude Desktop, Claude Code, or any MCP client. Control real motors by just asking:
"Find my motors and rotate the one on the bench two full turns, slowly."
Nothing is hardcoded: the server discovers your serial ports, auto-detects the
motors on the bus (the firmware's "Detect devices" command), and exposes the entire
firmware command set — every command in the servomotor library's catalog becomes an
MCP tool automatically (48 commands as of library 0.10.0), plus a few high-level tools
for everyday moves. It ships with a mock backend, so you can try the whole thing with
no hardware.
▶ 50-second video: the real motor and this session side by side — recorded 2026-09-09 on a bench M17; every line above is from the session log.
Step-by-step tutorial (boxed motor to "talk to it" in about twenty minutes): Talk to a servomotor from Claude Code on Hackster.
The first servomotor with an official MCP server. Open hardware, open firmware, open software — and now an open, AI-native control interface.
Then add it to Claude Desktop — copy the block from
examples/claude_desktop_config.json into your
claude_desktop_config.json, restart Claude Desktop, and ask:
"What serial ports do you see? Connect and find my motors."
See examples/demo_prompts.md for a scripted demo.
Plug an M17 (or a daisy-chain of them) into a USB↔RS-485 adapter and install the
[serial] extra — that's it, no configuration:
With the servomotor library installed the server uses the real serial backend
automatically. Without it, the server runs its simulator and says so: list_serial_ports
and connect return a notice field, and a warning goes to stderr. With uv, use
uvx --from 'servomotor-mcp[serial]' servomotor-mcp. In a session, the model then:
list_serial_ports — enumerates the machine's ports (macOS /dev/cu.*,
Windows COM*, Linux /dev/ttyUSB*), flagging USB serial adapters;connect — opens the port you (or it) picked, at 230400 baud;High-level (discovery + everyday motion):
| Tool | What it does |
|---|---|
list_serial_ports | Enumerate serial ports with USB metadata (call first). |
connect / disconnect | Open a port and auto-detect the motors on that bus. |
detect_devices | Re-scan the bus (reboots the motors on it). |
list_motors | Detected motors with live position/voltage/temperature/status. |
move_to / move_relative | Absolute / relative moves in degrees; waits for completion. |
stop | Emergency-stop one or all motors. |
get_motor_status | One motor's snapshot, fatal errors decoded to plain English. |
run_sequence | Choreographed steps ("draw a square"), incl. raw command steps. |
Plus one tool per firmware command, generated from the library's command catalog:
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, … — anything
the motor can do, the model can do. Motors are addressed by their alias number, their
16-hex-digit unique ID, or "all" (broadcast). Values are in friendly units (degrees,
seconds, degrees/s, volts, °C); the server converts to firmware units.
The server is a thin layer over the Gearotons servomotor Python library. The library is
data-driven — motor_commands.json defines every firmware command — and the server turns
that same catalog into MCP tools, so new library commands appear automatically. Tool calls
are forwarded straight to the hardware — no software clamping; full multi-turn travel, any
speed. The motor's own firmware protections (over-current / over-voltage /
over-temperature) still apply. The same tools run against the mock backend
(GEAROTONS_MOTOR_BACKEND=mock) for development and CI.
Environment variables (all optional):
GEAROTONS_MOTOR_BACKEND — auto (default: serial when the servomotor library is
installed, else mock), serial, or mock.GEAROTONS_SERIAL_PORT — default port for connect when the model doesn't pass one.GEAROTONS_DEFAULT_SPEED_DPS — default speed for move_to/move_relative (180).hardware_tests/ contains scripts that exercise the real serial path end to end
(port sweep, full command suite, stdio MCP session) against a bench motor.
uvx, on all four test adapters (motor found only where it truly is).MIT. Hardware, firmware, and software for the M17 are open-source — see github.com/tomrodinger/servomotor.