How robotmcp/ros-mcp-server works
Project type and purpose
• This is a middleware service (“ROS MCP Server”) that sits between Large Language Model (LLM) clients and ROS/ROS2-based robots. It provides bidirectional connectivity: translating natural-language commands into ROS messages, and streaming ROS data back to the LLM.
File structure
• Top-level artifacts:
• server.py – the entrypoint for the FastAPI/uvicorn-based MCP server
• utils/ – helper modules (network utilities, WebSocket manager)
• pyproject.toml – Python dependencies and project metadata
• examples/ – sample ROS1/ROS2 scenarios (Turtlesim, Gemini, Unitree, Docker setups)
• No frontend code: the client is any MCP-enabled LLM (Claude Desktop, ChatGPT plugin, Gemini, etc.)
• CI/CD workflows under .github/workflows for automated testing or deployment
README for additional insights
• Key components mentioned: LLM client, MCP server, ROS bridge node, ROS master, topics/services, sensor data streams.
• Technology stack: Python 3.10+, uvicorn (webserver), FastAPI (implied), websockets, rosbridge.
Main components and their interactions
a. LLM Client (Claude Desktop, ChatGPT plugin, Gemini, etc.)
• Opens a WebSocket/HTTP connection to the MCP Server
• Sends text-based commands; receives JSON messages describing ROS state and sensor data
b. MCP Server
• server.py launches a FastAPI app under uvicorn
• websocket_manager.py handles bidirectional JSON messaging
• network_utils.py manages low-level serialization/heartbeat, etc.
• Translates LLM requests into JSON-RPC calls over ROS bridge
• Manages subscriptions, publishes, service calls, parameter get/set
c. ROS Bridge Node (rosbridge_server)
• A ROS1/ROS2 node that exposes ROS master’s topic/service/parameter API over WebSocket or TCP
• Deployed on the target robot or simulation
d. ROS1/ROS2 Core
• Topic bus, service registry, parameter server – the heart of the robot’s runtime
e. Robot Hardware or Simulator
• Actual sensors/actuators (cameras, LIDAR, motors) in real or simulated environment (Isaac Sim)
Architectural patterns and design principles
• Microservice style: single responsibility for translation logic
• Adapter pattern: converting LLM JSON payloads to ROS bridge JSON-RPC and back
• Pub/Sub: subscribing to ROS topics for real-time updates
• Request/Response: invoking ROS services and returning results
Detail capture checklist
• Component names and purposes
• Data flow directions and protocols
• Key technologies and libraries
• Expandable extension points (utils, examples)
• Version-agnostic support (ROS1 & ROS2)
• Future features (Actions, permission controls)