Talk to a servomotor from Claude Code (20 min, $20 motor)

Four things in one package

The Gearotons M17 puts four things that you normally buy, wire and configure separately into one NEMA-17 package with no protrusions: the motor, the driver, the encoder and the motion controller. That integration is what makes it more affordable and much easier to use: nothing to source and match, nothing to wire between boards, nothing to assemble, nothing to configure so that one part talks to another. Connect power and one data cable and it works. Plug and play, for makers, classrooms and automation.

The documentation is written to be AI-friendly, so anyone working with an AI assistant will succeed: give the AI the docs and tell it what the motor logic should do. No coding experience needed; I have built many programs for these motors that way. Multiple motors work together on one bus, and you can drive them from an ESP32, Raspberry Pi or Arduino, or straight from a Mac or PC.

This tutorial goes from a boxed motor to "talk to it" in about twenty minutes. Here is the finished result, recorded on a bench motor: watch the 50-second video.

Step 1 — Wire it (2 minutes)

• Plug the USB-to-RS-485 adapter into your computer.
• Connect the adapter's A and B lines to the motor's RS-485 A and B pins (swapping A/B is the number one reason a motor "doesn't answer").
• Connect 12–24 V to the motor's power pins. Mind polarity.
• Power on. The motor's status LED should light.

Step 2 — Try it with no hardware first (2 minutes)

Install uv if you don't have it, then run the server with its built-in simulated motor:

uvx --from servomotor-mcp servomotor-mcp

If that starts without errors, the software side works. (Ctrl-C to stop it.)

Step 3 — Tell your AI assistant about the motor (3 minutes)

Claude Code (one line in a terminal):

claude mcp add gearotons-motor -- uvx --from "servomotor-mcp[serial]" servomotor-mcp

Claude Desktop — add this to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/, Windows: %APPDATA%\Claude\) and restart:

{
  "mcpServers": {
    "gearotons-motor": {
      "command": "uvx",
      "args": ["--from", "servomotor-mcp[serial]", "servomotor-mcp"]
    }
  }
}

Cursor — same block in ~/.cursor/mcp.json.

The [serial] extra pulls in the servomotor library so the server talks to real hardware. Without it you get the simulator.

Step 4 — Talk to it

Ask your assistant:

Find my motors, then move the one you find to 90 degrees and tell me where it actually ended up.

What happens under the hood, from a real session log: 1. list_serial_ports → it sees your adapter. 2. connect → opens the port at 230400 baud and auto-detects every motor on the bus (unique ID + alias). Nothing is hard-coded. 3. enable_mosfets, move_to 90 → the motor moves. The tool waits for completion and returns the encoder position. 4. get_comprehensive_position → commanded 90.0°, hall-sensor 90.0°.

Then try: "turn it two full rotations slowly, taking about 4 seconds, pause, and turn it back". The assistant queues three trapezoid_move commands (+720° over 4 s, a 1 s dwell, −720° over 4 s) and reads the encoder afterwards. On my bench it came back within 0.05° of where it started.

Step 5 — Prefer code? Six lines of Python

pip install servomotor

import time, servomotor
from servomotor import communication
communication.serial_port = "/dev/ttyUSB0"          # your adapter
servomotor.open_serial_port()
m = servomotor.M3("X", time_unit="seconds", position_unit="degrees")   # "X" = the motor's alias
m.enable_mosfets()
m.go_to_position(90, 1.0)                           # to 90°, over one second
time.sleep(1.2)
print(m.get_position())                             # the encoder's answer
m.disable_mosfets()
servomotor.close_serial_port()

Tested on the bench: 89.9999° after the move, 0.0001° after returning. Arduino, ESP32, RP2040, STM32: install the "Servomotor" library by Gearotons from the Library Manager; motor.trapezoidMove(2.0f, 3.0f) turns two rotations over three seconds.

Step 6 — More motors, any host

Give each motor an alias and they all share the same two wires; the assistant or your code addresses them by name. The host can be an ESP32, a Raspberry Pi, an Arduino, or a Mac or PC.

Specs

M17-34: 33.5 mm, 0.28 N·m, 210 g, $20. M17-40: 40.1 mm, 0.42 N·m, 285 g, $25. M17-48: 48.7 mm, 0.55 N·m, 360 g, $30. M17-60: 59.7 mm, 0.65 N·m, 470 g, $35.

All sizes: 12–24 V, up to about 1.1 A, up to 560 RPM, a 32 kHz control loop, RS-485 at 230400 baud, standard NEMA-17 mount.

Where the safety lives

The MCP server is a thin layer: it forwards commands straight to the motor, full range, any speed. The protection is in the motor's own firmware (over-current, over-voltage, over-temperature) and holds no matter what the model asks. Keep the rig free to move whatever the assistant asks, and use stop or pull power if in doubt.

Everything is open

Hardware, firmware and software are MIT-licensed: github.com/tomrodinger/servomotor. MCP server: github.com/Gearotons/servomotor-mcp. Docs: 9o.at/M17_1.5. Buy: gearotons.com (from $20).

Written with the help of an AI and verified by a human.