servomotor-mcp 0.2.0

MCP server to drive Gearotons M17 open-source servomotors from natural language (Claude / any MCP client) over RS-485.

servomotor-mcp

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 — as a small set of high-level tools. Connect it to Claude Desktop, Claude Code, or any MCP client and control real motors by just asking:

"Home everything, then draw a square with the X and Y axes."

It ships with a mock backend, so you can try the whole thing with no hardware.

The first servomotor with an official MCP server. Open hardware, open firmware, open software — and now an open, AI-native control interface.

---

Quickstart (no hardware, ~2 minutes)

# Run the server directly with uv (recommended):
uvx --from servomotor-mcp servomotor-mcp

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

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 motors do you have connected?" See examples/demo_prompts.md for the full scripted demo.

Drive real motors

Plug an M17 (or a daisy-chain of them) into a USB↔RS-485 adapter and switch the backend:

pip install 'servomotor-mcp[serial]'   # pulls in the Gearotons servomotor library
GEAROTONS_MOTOR_BACKEND=serial \
GEAROTONS_SERIAL_PORT=/dev/ttyUSB0 \
servomotor-mcp

Tools

Tool	What it does
list_motors	Discover motors on the bus + positions (call first).
move_to	Move a motor to an absolute angle (closed-loop).
move_relative	Nudge a motor by a delta.
trapezoid_move	Smooth accel/decel move (best for arms/plotters).
home	Home one or all motors.
get_status	Position / moving / voltage / errors.
stop	Halt one or all motors.
reset	Recover a motor from a latched fault (firmware system reset, ~2 s).
run_sequence	Run a choreographed sequence ("draw a square").

How it works

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

The server is a thin wrapper over the Gearotons servomotor Python library (high-level, unit-aware commands — no DIR/STEP timing). It maps friendly aliases to real motors and forwards each call straight to the hardware — no software clamping, so the motor does exactly what it's asked (full multi-turn travel, any speed). The motor's own firmware protections (over-current / over-voltage / over-temperature) still apply. The same intents run against the mock backend for development and CI. Configure the alias→address map via GEAROTONS_SERIAL_MOTORS (e.g. '{"x": 88}') or let the server auto-detect the bus.

Develop / test

pip install -e '.[dev]'
pytest                      # sequencer + mock-bus tests, no hardware needed
GEAROTONS_MOCK_SIM_SECONDS=0.4 servomotor-mcp   # lifelike timing for demos

Status

• ✅ MCP server, full tool surface, mock backend — done; unit tests pass.
• ✅ SerialBus real-hardware backend — verified against a physical M17 (fw 0.15.0.0): discovery, telemetry, closed-loop moves at 0.000° repeatability, and full multi-turn travel over MCP. See hardware_tests/.
• 🔜 Live FastMCP-over-stdio run with Claude Desktop needs a Python ≥3.10 host (tool logic already hardware-verified); plus the physical demo build + video. See demo spec.

License

MIT. Hardware, firmware, and software for the M17 are open-source — see github.com/tomrodinger/servomotor.