Metadata-Version: 2.4
Name: servomotor-mcp
Version: 0.2.0
Summary: MCP server to drive Gearotons M17 open-source servomotors from natural language (Claude / any MCP client) over RS-485.
Project-URL: Homepage, https://gearotons.com
Project-URL: Repository, https://github.com/Gearotons/servomotor-mcp
Project-URL: Issues, https://github.com/Gearotons/servomotor-mcp/issues
Project-URL: Documentation, https://github.com/Gearotons/servomotor-mcp#readme
Author: Gearotons
License: MIT
License-File: LICENSE
Keywords: ai,claude,mcp,nema17,open-source,robotics,rs485,servomotor
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: Manufacturing
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Scientific/Engineering
Classifier: Topic :: System :: Hardware
Requires-Python: >=3.10
Requires-Dist: mcp>=1.2.0
Provides-Extra: dev
Requires-Dist: pytest>=8.0; extra == 'dev'
Provides-Extra: serial
Requires-Dist: servomotor>=0.10.0; extra == 'serial'
Description-Content-Type: text/markdown

# servomotor-mcp

**Drive open-source [Gearotons M17](https://gearotons.com) servomotors from natural language.**

An [MCP](https://modelcontextprotocol.io) 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)

```bash
# 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`](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`](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:

```bash
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

```bash
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/`](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](../SPEC.md).

## License

MIT. Hardware, firmware, and software for the M17 are open-source —
see [github.com/tomrodinger/servomotor](https://github.com/tomrodinger/servomotor).
