rf/mcpositioner
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
mcpositioner/README.md
Ryan Malloy ce93070a04 Add README and CLAUDE.md 
README covers installation, hardware setup, tools, prompts, and
cross-server integration with mcnanovna for 3D pattern measurement.
CLAUDE.md provides project guidance for Claude Code.
2026-02-03 09:10:36 -07:00

2.8 KiB
Raw Blame History

mcpositioner

MCP server for controlling an ESP32 dual-axis antenna positioner over WiFi.

Drives two NEMA 17 stepper motors via TMC2209 drivers for theta (polar, 0-180°) and phi (azimuth, 0-360°) rotation. Designed for automated antenna radiation pattern measurement in coordination with a VNA.

Installation

# From PyPI (when published)
uvx mcpositioner

# From source
uv run mcpositioner

Hardware

  • ESP32 (any DevKit variant) running the firmware in firmware/
  • 2x TMC2209 stepper drivers in UART mode
  • 2x NEMA 17 stepper motors (0.9° or 1.8° step angle)
  • 24V power supply for motors (5V for ESP32)

See hardware/ for KiCad schematics showing the wiring.

Firmware

Build and flash with PlatformIO:

cd firmware
pio run -t upload

The ESP32 advertises itself as positioner.local via mDNS. Override with the MCPOSITIONER_HOST environment variable if needed.

MCP Tools

Tool Description
positioner_status Get theta/phi position, moving state, homed state
positioner_move Move to absolute theta/phi with optional wait
positioner_home StallGuard sensorless homing on one or both axes
positioner_stop Emergency stop all motors
positioner_config Get/set speed, acceleration, microstepping

Prompts

Prompt Description
home_positioner Guided homing with safety checks
configure_positioner Motion parameter tuning guide
measure_pattern_grid Cross-server 3D pattern measurement workflow

Cross-Server Pattern Measurement

This server controls positioning only. For 3D antenna pattern measurement, use together with mcnanovna (VNA MCP server):

  1. positioner_move (mcpositioner) — position antenna at theta/phi
  2. scan (mcnanovna) — measure S21 transmission
  3. Repeat across theta/phi grid
  4. Assemble pattern from collected measurements

The measure_pattern_grid prompt provides step-by-step guidance for this workflow.

Adding Both Servers to Claude Code

claude mcp add mcpositioner -- uvx mcpositioner
claude mcp add mcnanovna -- uvx mcnanovna

Configuration

Environment Variable Default Description
MCPOSITIONER_HOST positioner.local ESP32 hostname or IP

HTTP API (ESP32 Firmware)

The ESP32 exposes these endpoints:

Endpoint Method Description
/status GET Current position, moving, homed
/move POST {"theta_deg": 90, "phi_deg": 45}
/move/relative POST {"d_theta": 5, "d_phi": 10}
/home POST {"axis": "both"} (or "theta"/"phi")
/stop POST Emergency stop
/config GET/POST Motion parameters

License

MIT