so101-mcp
The server lets an MCP client read and safely move a calibrated SO-101 robot arm within configured joint limits.
Read current calibrated joint positions with
get_robot_state.List predefined safe named poses with
list_safe_poses.Move smoothly to a named safe pose with
move_to_pose.Move one or more joints to absolute degree positions with
move_joints.Rotate a single joint by a relative amount with
move_joint_by.Open, close, or cycle the gripper using calibrated safe endpoints with
open_gripper,close_gripper, andcycle_gripper.Movement requests are refused entirely if any target is outside configured limits or a limit is missing.
Drives a SO-101 / SO-ARM101 robot arm through an existing Hugging Face LeRobot installation and its calibration, exposing tools to read joint state and limits, list and move to taught poses, move individual or multiple joints by absolute or relative amounts, and open/close/cycle the gripper.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@so101-mcp open and close the gripper"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
so101-mcp

Cursor asks the arm, through so101-mcp, to open and close the gripper.
An MCP server that lets an AI assistant in any MCP client (Claude Code, Claude Desktop, Cursor, VS Code, ...) move a SO-101 / SO-ARM101 robot arm, with per-joint safety limits. It talks to the arm through your existing LeRobot installation and calibration.
Safety first. This software moves a real robot. It checks every target against per-joint limits and moves in small, bounded steps, but it does not detect collisions between links, with the table, or with people. Keep the work area clear, keep a hand on the power supply, and never run it with anyone near the arm. Use at your own risk (see the license).
Not affiliated with Hugging Face, TheRobotStudio, Anthropic or Cursor.
Tools
Tool | What it does |
| Reads the current joint positions. No movement. |
| Lists the named poses defined in |
| Moves smoothly to a named pose. |
| Moves one or more joints to absolute positions (degrees). All joints move together. |
| Rotates one joint by a relative amount. |
| Gripper control between configured endpoints. |
Every movement tool refuses the whole request, and moves nothing, if any target is outside the configured limits or a limit is missing.
Related MCP server: SO-ARM100 Robot Control MCP
Joints
# | Name | Moves |
1 |
| base rotation (left/right) |
2 |
| upper arm (forward/back) |
3 |
| elbow |
4 |
| wrist up/down |
5 |
| rotation of the gripper |
6 |
| opening (about 0-100) |
Sign conventions depend on your calibration and assembly. On the author's arm, negative shoulder_pan turns left. Check each joint with a small move before relying on a direction.
Requirements
A SO-101 arm, already calibrated with LeRobot (the server refuses to run on an uncalibrated arm).
uv and Python 3.12+.
Install
git clone https://github.com/Tibe31/so101-mcp
cd so101-mcp
uv sync --extra robotThe robot extra installs LeRobot and its dependencies (large download). Run this once yourself, so your MCP client does not time out on first start.
If the arm is not calibrated yet:
uv run --extra robot lerobot-calibrate --robot.type=so101_follower --robot.port=COM4 --robot.id=my_armConfigure
cp config.example.json config.json # copy config.example.json config.json on WindowsSet
port(for exampleCOM4or/dev/ttyACM0) androbot_id(the id used at calibration time).Generate the joint limits from your calibration file (the path is printed by
lerobot-calibrate; it lives under~/.cache/huggingface/lerobot/calibration/unlessHF_LEROBOT_CALIBRATIONis set):uv run so101-limits path/to/my_arm.json --margin 3Paste the printed
limitsintoconfig.json. The margin keeps the motors a few degrees away from the mechanical end stops. The numbers assume LeRobot's degree mode (the default forSO101FollowerConfig).Set the gripper: read
get_robot_statewith the gripper fully open and fully closed, then fillgripper.open,gripper.closedandlimits.gripper([min, max]).Optional: add poses. Put the arm in a safe position, read it with
get_robot_state, and copy the values intoposes:"poses": { "rest": {"shoulder_pan": 0, "shoulder_lift": -103.9, "elbow_flex": 93.4, "wrist_flex": 78.0, "wrist_roll": -90.0, "gripper": 2.0} }Pose values must fall inside the limits, and the gripper in a pose must not be below
limits.gripper.
max_step_degrees (0-2) and updates_per_second (1-20) set the speed: roughly their product in degrees per second. Increase them gradually.
config.json holds your own port, id, limits and poses: it is git-ignored.
Use with an MCP client
The server speaks MCP over stdio, so it works with any MCP client. Before adding it, check that it starts on its own: uv run --extra robot so101-mcp should wait silently for input (stop it with Ctrl+C). Use the absolute path of config.json in SO101_MCP_CONFIG, so it does not depend on the working directory.
Claude Code
Add the server (replace the paths with yours; on Windows use
C:\path\to\so101-mcp):claude mcp add so101 --env SO101_MCP_CONFIG=/path/to/so101-mcp/config.json -- \ uv run --directory /path/to/so101-mcp --extra robot so101-mcpBy default the server is available only in the current project. Add
--scope userto make it available everywhere.Check it:
claude mcp listshould showso101as connected. Inside Claude Code,/mcpshows its status and tools.Ask for something small first: "read the robot state", then "rotate shoulder_pan by 5 degrees".
Claude Code asks for permission the first time a tool is used. Approve movement tools one call at a time rather than "always allow".
To remove it: claude mcp remove so101.
Claude Desktop
Edit claude_desktop_config.json (Settings > Developer > Edit Config), then restart Claude Desktop:
{
"mcpServers": {
"so101": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\so101-mcp", "--extra", "robot", "so101-mcp"],
"env": {"SO101_MCP_CONFIG": "C:\\path\\to\\so101-mcp\\config.json"}
}
}
}Cursor
Create .cursor/mcp.json in your project (or ~/.cursor/mcp.json for all projects). The format is the same as for Claude Desktop:
{
"mcpServers": {
"so101": {
"command": "uv",
"args": ["run", "--directory", "C:\\path\\to\\so101-mcp", "--extra", "robot", "so101-mcp"],
"env": {"SO101_MCP_CONFIG": "C:\\path\\to\\so101-mcp\\config.json"}
}
}
}Then enable so101 in Cursor's MCP settings. Keep tool approval on (no auto-run) for the movement tools.
Other clients
Any client that can launch a stdio MCP server works: use uv as the command, ["run", "--directory", "<repo>", "--extra", "robot", "so101-mcp"] as the arguments and SO101_MCP_CONFIG as an environment variable.
All clients
Only one client at a time can hold the arm's serial port: close LeLab, LeRobot scripts and any other MCP client first (for example, Claude Desktop while using Cursor). Whether a client asks for confirmation before moving the arm depends on the client; the server only marks movement tools as destructive.
Then ask things like "read the robot state", "rotate joint 1 left by 30 degrees" or "go to the rest pose".
Agent skill (optional)
skills/so101-robot/SKILL.md is a skill file that teaches an agent when and how to use these tools safely: read the state first, start with small moves, never get around a refused limit, stop on anything unexpected. The MCP server works without it, but it makes the agent's behavior more careful.
To use it with Claude Code, copy the folder into your skills directory:
cp -r skills/so101-robot ~/.claude/skills/ # all projects
# or: cp -r skills/so101-robot .claude/skills/ # this project onlyOther agents that read SKILL.md files can use the same folder; check where your client looks for skills.
Troubleshooting
Access is denied/ClearCommErroron the port: another program holds the serial port (LeLab, a LeRobot script, another MCP client). Close it, or replug the USB cable, then restart the server.Missing verified limit for joint ...: the joint has no[min, max]inlimits.Target for ... is outside the locally configured safe limits: the target (or a pose value) is outside the limits. Nothing moved.LeRobot is not installed: install withuv sync --extra robotand start the server with--extra robot.The reading is a few tenths of a degree off the target: normal motor tolerance and settling.
Development
uv run pytestThe tests use a fake robot, so no hardware or LeRobot install is needed.
Limitations
No collision checking (links, table, people). No kinematics: moves are in joint space, not centimeters.
Fixed speed profile, set only through the config.
A movement cannot be interrupted. A single move can run for up to about 40 seconds (600 steps at the slowest rate) while the server holds a lock, and the MCP client cannot cancel it. If a step fails midway, the arm stays where it stopped. Keep the power supply within reach.
Limits are checked on the final target only. The path between start and target is a straight line in joint space and is not checked for collisions.
The server does not manage the arm's torque when it exits. Do not assume the arm will hold or release its position; check this on your setup.
config.jsonis read once at startup: restart the server after changing limits or poses.Movement tools carry MCP annotations (
destructiveHint), so clients can ask for confirmation before moving the arm. Keep that confirmation enabled.
License
MIT, see LICENSE.
Available Tools
8 toolsclose_gripperBDestructive
Slowly close gripper to the operator-verified safe position.
Inputs: no named parameters.
cycle_gripperADestructive
Open then close gripper a specified number of times (1-5), using operator-validated calibrated endpoints.
Inputs: times (required).
get_robot_stateARead-only
Read calibrated motor positions (no intentional movement).
Inputs: no named parameters.
list_safe_posesARead-only
Show only pre-taught named poses. Never guess an extreme pose.
Inputs: no named parameters. Returns: result
move_joint_byADestructive
Rotate a single joint by a relative amount from its current position. Example: joint="shoulder_pan", delta_degrees=-10 (negative pan = left). The final position must be inside the limits in config.json, otherwise nothing moves.
Inputs: joint (required), delta_degrees (required).
move_jointsADestructive
Move one or more joints to absolute positions (degrees; gripper 0-100). Example: {"shoulder_pan": -50, "wrist_roll": 0}. Joints not listed stay in place. Every target must be inside the limits in config.json, otherwise nothing moves. Do not use if work area is obstructed.
Inputs: targets (required).
move_to_poseADestructive
Move slowly to a locally taught and verified safe pose by name. Do not use if work area is obstructed.
Inputs: name (required).
open_gripperBDestructive
Slowly open gripper to the operator-verified safe position.
Inputs: no named parameters.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
Each tool maps to a distinct action on a distinct target: read state, list named poses, move to a named pose, absolute multi-joint moves, relative single-joint moves, and three gripper operations. The only mild overlap is move_joints vs. move_joint_by, but the descriptions clearly separate absolute/multi-joint from relative/single-joint semantics, and cycle_gripper is distinguished from open/close by its repeat count.
All names follow a consistent snake_case verb_noun pattern (get_*, list_*, move_*, cycle_*, open_*, close_*) with predictable, domain-specific nouns. No mixed conventions or vague verbs anywhere in the set.
Eight tools is a well-scoped surface for a robot arm: state read, pose listing, three movement primitives, and three gripper operations. Nothing feels redundant or padded, and no important primitive is obviously duplicated.
The surface covers perception (get_robot_state, list_safe_poses), motion (move_to_pose, move_joints, move_joint_by), and end-effector control (open/close/cycle_gripper) with clear lifecycle coverage. Minor gaps exist: no explicit stop/halt or return-to-home primitive and no way to teach/register a new safe pose, though the latter appears intentionally done by an operator outside the toolset.
Related MCP Connectors
Zero-auth ROS 2 Humanoid, Q3 Proxemics, 3-Level Voice Arbiter, A2A-MCP Bridge & W3C VC 2.0.
MCP server that lets AI assistants use all OneSchema features exposed via the public API.
Use AI models for chat, image, and video generation from Claude Code and other MCP hosts.
Cross-vendor AI memory over MCP. One semantic store, readable and writeable from every MCP client.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables LLM-based AI agents to control SO-ARM100 and SO-101 robots through natural language commands and camera feedback. It supports various transport protocols and provides tools for both autonomous robotic movement and manual keyboard operation.87Apache 2.0
- AlicenseNot gradedqualityDmaintenanceEnables AI agents to control SO-ARM100 and LeKiwi robots using natural language instructions and integrated camera vision. It supports multiple communication transports and includes a CLI agent compatible with Claude, Gemini, and GPT models.Apache 2.0
- FlicenseNot gradedqualityDmaintenanceEnables natural language control of an esieabot robot (motors, servo, camera) through Claude Desktop or MCP Inspector.-
- AlicenseNot gradedqualityDmaintenanceEnables AI systems to control the Reachy Mini robot—speak, listen, see, and express emotions through physical movement. Compatible with Claude, GPT, Grok, and other MCP-compatible AIs.MIT