Gearotons M17 Servomotor

servomotor-mcp

オープンソースのGearotons M17サーボモーターを、自然言語で操作できます。

M17（NEMA-17サイズの一体型クローズドループRS-485サーボモーター）を、Claude Desktop、Claude Code、または任意のMCPクライアントから利用できるMCPサーバーです。次のように頼むだけで、実際のモーターを操作できます。

「モーターを見つけて、ベンチに置いてあるモーターをゆっくり2回転させて。」

設定がハードコードされていることはありません。サーバーがシリアルポートを検出し、バス上のモーターを自動検出し（ファームウェアの「Detect devices」コマンドを使用）、ファームウェアのコマンドセット全体を公開します。servomotorライブラリのカタログにある各コマンドがMCPツールとして自動的に利用可能になります（ライブラリ0.10.0時点で48コマンド）。さらに、日常的な動作に使える上位レベルのツールもいくつか備えています。モックバックエンドも付属しているため、ハードウェアがなくてもすべて試せます。

▶ 50秒の動画：実際のモーターとセッションを並べて紹介 — 2026-09-09にベンチ上のM17で撮影。上記の各行はすべてセッションログからのものです。

ステップバイステップのチュートリアル（箱に入ったモーターを、約20分で「話しかけて操作」できるようにします）：HacksterのClaude Codeからサーボモーターに話しかけるをご覧ください。

公式MCPサーバーを備えた初のサーボモーターです。オープンハードウェア、オープンファームウェア、オープンソフトウェア。そして今、オープンでAIネイティブな制御インターフェースが加わりました。

---

クイックスタート（ハードウェア不要、約2分）

# Run the server directly with uv (recommended). This runs the SIMULATOR —
# for real motors see "Drive real motors" below:
uvx --from servomotor-mcp servomotor-mcp

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

次に、Claude Desktopに追加します。examples/claude_desktop_config.jsonのブロックをclaude_desktop_config.jsonにコピーし、Claude Desktopを再起動して、次のように尋ねてください。 「どのシリアルポートが見えますか？接続してモーターを探してください。」 スクリプト形式のデモについては、examples/demo_prompts.mdをご覧ください。

実際のモーターを操作する

M17（またはデイジーチェーン接続した複数のM17）をUSB↔RS-485アダプターに接続し、[serial]エクストラをインストールすれば完了です。設定は不要です。

pip install 'servomotor-mcp[serial]'   # pulls in the Gearotons servomotor library
servomotor-mcp

servomotorライブラリがインストールされている場合、サーバーは実際のシリアルバックエンドを自動的に使用します。インストールされていない場合、サーバーはシミュレーターを実行し、その旨を通知します。list_serial_portsとconnectはnoticeフィールドを返し、警告は標準エラー出力に表示されます。uvを使う場合は、uvx --from 'servomotor-mcp[serial]' servomotor-mcpを使用してください。セッションでは、モデルは次のように動作します。

1. list_serial_ports — マシンのポートを列挙します（macOS /dev/cu.*、Windows COM*、Linux /dev/ttyUSB*）。USBシリアルアダプターにはフラグを付けます。
2. connect — 選択した（または選択された）ポートを230400ボーで開きます。
3. バス上のすべてのモーターを自動検出します（固有IDとエイリアス）。アドレスマップを作成する必要はありません。
4. モーターを操作します。アダプターが複数ある場合は、どれを使うかを平易な英語で伝えてください。

ツール

高レベル（検出＋日常的な操作）：

ツール	機能
list_serial_ports	USB メタデータ付きでシリアルポートを列挙します（最初に呼び出してください）。
connect / disconnect	ポートを開き、そのバス上のモーターを自動検出します。
detect_devices	バスを再スキャンします（バス上のモーターを再起動します）。
list_motors	検出されたモーターの位置／電圧／温度／ステータスをリアルタイムで表示します。
move_to / move_relative	絶対移動／相対移動を度単位で実行し、完了を待ちます。
stop	1 台またはすべてのモーターを緊急停止します。
get_motor_status	1 台のモーターのスナップショットを取得し、致命的なエラーをわかりやすい英語に変換します。
run_sequence	演出されたステップ（「正方形を描く」など）を実行します。生コマンドのステップも含みます。

さらに、ライブラリのコマンドカタログから生成される、ファームウェアコマンドごとのツールがあります： enable_mosfets、go_to_position、move_with_velocity、move_with_acceleration、 multimove、homing、zero_position、get_position、get_temperature、 set_device_alias、set_pid_constants、system_reset、vibrate、ping、… — モーターが実行できる操作は、すべてモデルも実行できます。モーターはエイリアス番号、16 桁の 16 進数の一意の ID、または "all"（ブロードキャスト）で指定します。値の単位は扱いやすい単位（度、秒、度/秒、ボルト、°C）で、サーバーがファームウェアの単位に変換します。

仕組み

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

このサーバーは、Gearotons の servomotor Python ライブラリを薄くラップしたものです。このライブラリはデータ駆動型で、motor_commands.json がすべてのファームウェアコマンドを定義しています。サーバーは同じカタログから MCP ツールを生成するため、ライブラリに新しいコマンドが追加されると自動的に利用可能になります。ツールの呼び出しはハードウェアに直接転送されます。ソフトウェアによる制限はなく、複数回転の全範囲を任意の速度で移動できます。モーター独自のファームウェア保護（過電流／過電圧／過熱）は引き続き適用されます。同じツールを、開発や CI ではモックバックエンド（GEAROTONS_MOTOR_BACKEND=mock）に対して実行できます。

環境変数（すべて任意）：

• GEAROTONS_MOTOR_BACKEND — auto（デフォルト：servomotor ライブラリがインストールされていればシリアル、それ以外はモック）、serial、または mock。
• GEAROTONS_SERIAL_PORT — モデルがポートを指定しない場合に connect で使用するデフォルトポート。
• GEAROTONS_DEFAULT_SPEED_DPS — move_to／move_relative のデフォルト速度（180）。

開発／テスト

pip install -e '.[dev]'
GEAROTONS_MOTOR_BACKEND=mock pytest     # catalog + mock-bus + server-tool tests

hardware_tests/ には、ベンチ上のモーターに対して実際のシリアル経路をエンドツーエンドでテストするスクリプトが含まれています（ポートの一括スキャン、全コマンド一式、stdio MCP セッション）。

ステータス

• ✅ シリアルポートの検出とバスの自動検出を含む、ファームウェアコマンドの全機能（48 コマンド） — 実際の stdio MCP セッションと uvx を使い、4 種類すべてのテスト用アダプターで 実機の M17 にて検証済み（モーターは実際に接続されている場合のみ検出）。
• ✅ モックバックエンドと 39 件のユニットテストを備え、ハードウェアは不要です。
• ✅ pyserial による列挙を通じた、macOS／Windows／Linux のクロスプラットフォーム対応ポート処理。

ライセンス

MIT。M17 のハードウェア、ファームウェア、ソフトウェアはオープンソースです — github.com/tomrodinger/servomotor をご覧ください。