Skip to content
Back to search

robot_MCP

A simple MCP server for the SO-ARM100 control

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ilialarchenko--robot-mcp/badge.svg)](/listings/ilialarchenko--robot-mcp)

HTML

<a href="/listings/ilialarchenko--robot-mcp"><img src="/api/listings/ilialarchenko--robot-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

1. Install Dependencies

For simplicity I use simple pip instead of uv that is often recommended in MCP tutorials - it works just fine.

python -m venv .venv
source .venv/bin/activate  # or .venv\Scripts\activate on Windows
pip install -r requirements.txt

It may be required to install lerobot separately, just use the official instructions from the [lerobot repository](https://github.com/huggingface/lerobot)

2. Connect Your Robot

- Connect SO-ARM100 via USB - Update `config.py` with your serial port for so-arm (e.g., `/dev/tty.usbmodem58FD0168731`) or robot_ip for lekiwi (e.g., `192.168.1.1`) - Connect cameras and update `config.py` with the correct indices and names (for `lekiwi` only names are important)

3. Use the robot

**๐Ÿ” Check Robot Status and Calibration:**

python check_positions.py

This will show you the current robot state without actual control. Move your robot manually to make sure it is properly calibrated and configured.

After the latest update, lerobot is using the normalized joints states instead of degrees. You can update `MOTOR_NORMALIZED_TO_DEGREE_MAPPING` in `config.py` to match your robot calibration. You will need to update these values every time you recalibrate the robot.

**๐ŸŽฎ Manual Keyboard Control:**

python keyboard_controller.py

Now you can try to control the robot manually using the keyboard. Test it before moving on to the MCP step, to make sure it works properly.

**๐Ÿ› ๏ธ MCP server in the dev mode**

mcp dev mcp_robot_server.py

Final test step - to debug the MCP server, use the UI to connect to it and try to send some requests.

**๐Ÿค– AI Agent Control (MCP Server):**

WARNING: using MCP server itself is free, but it requires MCP client that will send requests to some LLM. Generally it is not free - and controlling the robot with MCP can become expensive, as it sends multiple agentic requests with images that use a lot of tokens. Make sure you understand and control your token usage and corresponding costs before doing it. The actual cost depends on the client and models you use, and it is your responsibility to monitor and control it.

mcp run mcp_robot_server.py --transport SELECTED_TRANSPORT

Supports: `stdio`, `sse`, `streamable-http`

Now your server can be added to any MCP client.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md ยท README ยท 221 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # SO-ARM100 Robot Control with MCP
  2. [![Watch the full tutorial](https://img.youtube.com/vi/EmpQQd7jRqs/0.jpg)](https://youtu.be/EmpQQd7jRqs)
  3. A companion repository to my video about MCP server for the robot:
  4. - **MCP Server** for LLM-based AI agents (Claude Desktop, Cursor, Windsurf, etc.) to control the robot
  5. - **Direct keyboard control** for manual operation
  6. - **CLI AI Agent** can use it directly to control the robot with Claude, Gemini or GPT model
  7. If you want to know more about MCP refer to the [official MCP documentation](https://github.com/modelcontextprotocol/python-sdk)
  8. This repository suppose to work with the SO-ARM100 / 101 robots. Refer to [lerobot SO-101 setup guide](https://huggingface.co/docs/lerobot/so101) for the detailed instructions on how to setup the robot.
  9. Update! Now it partially supports [LeKiwi](https://github.com/SIGRobotics-UIUC/LeKiwi) (only arm, the mobile base control through MCP is TBD).
  10. I also added a simple agent that uses MCP server to control the robot. It supports Claude, Gemini and GPT models. In my experience Claude is the best and GPT is not so good, Gemini is in between.
  11. After I released the video and this repository, LeRobot released a significant update of the library that breaks the compatibility with the original code.
  12. If you want to use the original code and exactly follow the video, please use [this release](https://github.com/IliaLarchenko/robot_MCP/tree/v0.0.1).
  13. ## Quick Start
  14. ### 1. Install Dependencies
  15. For simplicity I use simple pip instead of uv that is often recommended in MCP tutorials - it works just fine.
  16. ```bash
  17. python -m venv .venv
  18. source .venv/bin/activate # or .venv\Scripts\activate on Windows
  19. pip install -r requirements.txt
  20. ```
  21. It may be required to install lerobot separately, just use the official instructions from the [lerobot repository](https://github.com/huggingface/lerobot)
  22. ### 2. Connect Your Robot
  23. - Connect SO-ARM100 via USB
  24. - Update `config.py` with your serial port for so-arm (e.g., `/dev/tty.usbmodem58FD0168731`) or robot_ip for lekiwi (e.g., `192.168.1.1`)
  25. - Connect cameras and update `config.py` with the correct indices and names (for `lekiwi` only names are important)
  26. ### 3. Use the robot
  27. **๐Ÿ” Check Robot Status and Calibration:**
  28. ```bash
  29. python check_positions.py
  30. ```
  31. This will show you the current robot state without actual control. Move your robot manually to make sure it is properly calibrated and configured.
  32. After the latest update, lerobot is using the normalized joints states instead of degrees. You can update `MOTOR_NORMALIZED_TO_DEGREE_MAPPING` in `config.py` to match your robot calibration. You will need to update these values every time you recalibrate the robot.
  33. **๐ŸŽฎ Manual Keyboard Control:**
  34. ```bash
  35. python keyboard_controller.py
  36. ```
  37. Now you can try to control the robot manually using the keyboard. Test it before moving on to the MCP step, to make sure it works properly.
  38. **๐Ÿ› ๏ธ MCP server in the dev mode**
  39. ```bash
  40. mcp dev mcp_robot_server.py
  41. ```
  42. Final test step - to debug the MCP server, use the UI to connect to it and try to send some requests.
  43. **๐Ÿค– AI Agent Control (MCP Server):**
  44. WARNING: using MCP server itself is free, but it requires MCP client that will send requests to some LLM. Generally it is not free - and controlling the robot with MCP can become expensive, as it sends multiple agentic requests with images that use a lot of tokens. Make sure you understand and control your token usage and corresponding costs before doing it. The actual cost depends on the client and models you use, and it is your responsibility to monitor and control it.
  45. ```bash
  46. mcp run mcp_robot_server.py --transport SELECTED_TRANSPORT
  47. ```
  48. Supports: `stdio`, `sse`, `streamable-http`
  49. Now your server can be added to any MCP client.
  50. ## Connecting MCP Clients
  51. Different clients can support different transports, you can choose the one that works best for you. The functionality is the same.
  52. ### STDIO transport
  53. Add to your MCP configuration:
  54. ```json
  55. {
  56. "mcpServers": {
  57. "SO-ARM100 robot controller": {
  58. "command": "/path/to/.venv/bin/python",
  59. "args": ["/path/to/mcp_robot_server.py"]
  60. }
  61. }
  62. }
  63. ```
  64. ### SEE transport
  65. Run the server in terminal with the SSE transport:
  66. ```bash
  67. mcp run mcp_robot_server.py --transport sse
  68. ```
  69. Add to your MCP configuration:
  70. ```json
  71. {
  72. "mcpServers": {
  73. "SO-ARM100 robot controller": {
  74. "url": "http://127.0.0.1:3001/sse"
  75. }
  76. }
  77. }
  78. ```
  79. ### Streamed-HTTP transport
  80. It is suppose to be a replacement for SSE but currently not so many clients support it.
  81. Run the server in terminal with the Streamed-HTTP transport:
  82. ```bash
  83. mcp run mcp_robot_server.py --transport streamable-http
  84. ```
  85. Add to your MCP configuration:
  86. ```json
  87. {
  88. "mcpServers": {
  89. "SO-ARM100 robot controller": {
  90. "url": "http://127.0.0.1:3001/mcp"
  91. }
  92. }
  93. }
  94. ```
  95. ## Using the robot with MCP
  96. Now you can go to you Client and it should be able to control the robot when you give it the natural language instructions.
  97. ## Using the Agent
  98. Start the MCP server with the SSE transport:
  99. ```bash
  100. mcp run mcp_robot_server.py --transport sse
  101. ```
  102. Now you can use the AI agent to control the robot with natural language instructions.
  103. ### Configuration
  104. Create a `.env` file in the project root with your API keys:
  105. ```bash
  106. # API Keys (at least one required)
  107. ANTHROPIC_API_KEY=your_anthropic_api_key_here
  108. GEMINI_API_KEY=your_gemini_api_key_here
  109. OPENAI_API_KEY=your_openai_api_key_here
  110. # MCP Server Configuration (optional)
  111. MCP_SERVER_IP=127.0.0.1
  112. MCP_PORT=3001
  113. ```
  114. ### Basic Usage
  115. ```bash
  116. python agent.py
  117. ```
  118. ### Advanced Usage
  119. ```bash
  120. # Use Gemini instead of Claude
  121. python agent.py --model gemini-2.5-flash
  122. # Override API key
  123. python agent.py --api-key your_api_key_here
  124. # Enable image viewer window
  125. python agent.py --show-images
  126. # Increase thinking budget for better reasoning
  127. python agent.py --thinking-budget 2048
  128. # Custom MCP server location
  129. python agent.py --mcp-server-ip 192.168.1.100 --mcp-port 3002
  130. ```
  131. ### Supported Models (examples)
  132. **Claude (Anthropic):**
  133. - `claude-3-7-sonnet-latest` (default)
  134. - All models support thinking, streaming, and multimodal tool results
  135. **Gemini (Google):**
  136. - `gemini-2.5-flash`
  137. - `gemini-2.5-pro`
  138. - Use 2.5+ models as they support thinking feature
  139. **GPT (OpenAI):**
  140. - `gpt-4o` and variants
  141. - The rest of the models mostly don't support thinking or tool calling.
  142. Overall I didn't manage to get good results with GPT models.
  143. ### Parameters
  144. - `--model`: LLM model to use (default: claude-3-7-sonnet-latest)
  145. - `--api-key`: API key override (uses .env file by default)
  146. - `--show-images`: Display robot camera images in a window
  147. - `--thinking-budget`: Thinking tokens budget (default: 1024, 0 to disable)
  148. - `--thinking-every-n`: Use thinking every N steps (default: 3)
  149. - `--mcp-server-ip`: MCP server IP address (default: 127.0.0.1)
  150. - `--mcp-port`: MCP server port (default: 3001)
  151. ### Cost Considerations
  152. **Token Usage:**
  153. - Claude counts MCP images in input tokens (more expensive for vision tasks)
  154. - Gemini doesn't count MCP images in tokens (token usage will be displayed only for text)
  155. - Thinking tokens add to the cost but improve reasoning quality

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If itโ€™s helped, pass it on.