Gearotons/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 — 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.
---
Quickstart (no hardware, ~2 minutes)
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.
Drive real motors
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:
1. list_serial_ports — enumerates the machine's ports (macOS /dev/cu.*,
Windows COM*, Linux /dev/ttyUSB*), flagging USB serial adapters;
2. connect — opens the port you (or it) picked, at 230400 baud;
3. auto-detects every motor on that bus (unique ID + alias) — no address maps to write;
4. drives them. Tell it in plain English which adapter to use if you have several.
Tools
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. |