DOCSEARCHbyAlgolia
Submit Docs

ROS MCP Server

repository·main·Indexed 23 days ago

https://github.com/robotmcp/ros-mcp-server

A bridge between AI Language Models and the Robot Operating System (ROS/ROS 2) using the Model Context Protocol (MCP). It enables AI agents to discover, observe, and control robots through natural language by interacting with ROS topics, services, and actions. Supports integration with Gemini CLI and provides examples for Turtlesim, Isaac Sim (LIMO), and real AgileX LIMO robots.

Tokens
28K
Snippets
84
Records
153
Agent score
78%

What's inside ros-mcp-server

  1. Overview of ROS MCP Server

    main

    ROS MCP Server is a Model Context Protocol (MCP) server that enables bidirectional communication between Large Language Models (LLMs) like Claude, GPT, and Gemini and robots running ROS (Robot Operating System) or ROS 2.

    Key capabilities include:

    • No source code changes: Integration is achieved by adding a rosbridge node to your existing ROS setup.
    • Bidirectional control and observation: LLMs can both issue commands to control the robot and subscribe to topics to observe sensor data and robot state in real time.
    • Deep ROS discovery: The server guides the LLM to discover available topics, services, actions, and their specific types (including custom ones), allowing the LLM to use the correct syntax without manual configuration.
    • Broad compatibility: Works with ROS 1 and ROS 2 (including Jazzy and Humble) and any MCP-compliant client (e.g., Claude Desktop, Cursor, ChatGPT, Claude Code, Gemini CLI).

  2. Overview of ROS MCP Tool Categories

    main

    The ros-mcp-server provides 31 tools organized into the following functional categories:

    • Connection: connect_to_robot, ping_robot
    • Robot Config: get_verified_robot_spec, get_verified_robots_list, detect_ros_version
    • Topics: get_topics, get_topic_type, get_message_details, get_topic_publishers, get_topic_subscribers, inspect_all_topics, subscribe_once, publish_once, subscribe_for_duration, publish_for_durations
    • Services: get_services, get_service_type, get_service_details, get_service_providers, inspect_all_services, call_service
    • Nodes: get_nodes, get_node_details, inspect_all_nodes
    • Parameters: get_parameter, set_parameter, has_parameter, delete_parameter, get_parameters, inspect_all_parameters, get_parameter_details
    • Actions: get_actions, get_action_type, get_action_details, get_action_status, inspect_all_actions, send_action_goal, cancel_action_goal
    • Images: view_saved_image

  3. Compare STDIO vs HTTP transport

    main

    Choosing between the default stdio transport and streamable-http depends on your deployment needs:

    FeatureSTDIO (Default)HTTP/Streamable-HTTP
    Best forLocal development, single-user setupsRemote access, multiple clients, production deployments
    ProsSimple setup, no network configuration neededNetwork accessible, multiple clients can connect
    ConsMCP server and AI client must be on the same machineRequires network configuration, server must be started manually
    Use caseRunning MCP server directly with your AI clientRemote robots, team environments, web-based clients, development

  4. How ROS MCP Server components work together

    main

    The ROS MCP Server follows a modular architecture built on FastMCP. It uses three primary abstractions to interact with ROS via a rosbridge WebSocket interface:

    1. Tools: The main interface for active interaction (e.g., calling services, publishing topics). Tools use a WebSocketManager to communicate with the robot.
    2. Resources: Provide read-only, structured JSON data about the system state (e.g., lists of all active topics or nodes) via URIs.
    3. Prompts: Interactive templates that guide users through testing or using specific tool categories.

    All components are registered to a central FastMCP instance and rely on a shared WebSocketManager to handle the connection lifecycle and ROS communication.

  5. How the LIMO ROS-MCP framework works

    main

    The LIMO integration uses a layered communication approach:

    1. AI System: Communicates with the ROS-MCP via the MCP protocol.
    2. ROS-MCP Server: Connects to the robot via ROSbridge.
    3. ROSbridge: Converts ROS messages into JSON format over WebSockets.
    4. ROS Nodes: Handle hardware control (motors, sensors) and topic exchange on the LIMO.

    A critical component is the cmd_vel_repeat.py node. Because ROS-MCP might not publish at a perfectly steady high frequency, this node subscribes to cmd_vel (from MCP) and re-publishes it to cmd_vel_to_motor at a fixed frequency to ensure smooth movement.

  6. Launch ROS-MCP communication services on Unitree GO2

    main

    To enable the ros-mcp-server to interact with the robot, you must run both the rosbridge server and the camera bridge script simultaneously on the Unitree GO2. Open two separate terminal sessions on the robot:

    Terminal 1: Launch rosbridge

    ros2 launch rosbridge_server rosbridge_websocket_launch.xml

    Terminal 2: Launch camera script

    cd ~/cyclonedds_ws/src/image_process/
python3 camera_bridge.py
    ros2 launch rosbridge_server rosbridge_websocket_launch.xml

# In another terminal
cd ~/cyclonedds_ws/src/image_process/
python3 camera_bridge.py

  8. Run ROS and Rosbridge on the target machine

    main

    For the MCP server to interact with ROS, you must have a ROS environment running with rosbridge active. In your WSL terminal, run:

    source /opt/ros/jazzy/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml & ros2 run turtlesim turtlesim_node

    Alternatively, if you have the helper script available, you can run:

    ./launch_ros.sh
    source /opt/ros/jazzy/setup.bash
ros2 launch rosbridge_server rosbridge_websocket_launch.xml & ros2 run turtlesim turtlesim_node

  9. Configure your AI client for pip installation

    main

    When installed via pip, the ros-mcp command is available directly in your environment. When configuring your AI client (like Claude Code or other MCP-compatible clients), use ros-mcp as the command instead of uvx ros-mcp.

    Claude Code configuration: Use the claude mcp add command with the --transport=stdio flag.

    JSON configuration (for other clients): If your client uses a JSON configuration file, specify ros-mcp as the command and pass --transport=stdio in the arguments array.

  10. Prerequisites for Gemini-CLI with ROS-MCP-Server

    main

    Before running the Gemini-CLI demo with ROS-MCP-Server, ensure the following components are installed and configured:

    • Gemini-CLI: Installed via the official repository.
    • ROS or ROS2: A working ROS installation. You can verify this by running turtlesim.
    • ROS-MCP-Server: Installed following the Installation Guide (excluding Claude Desktop specific steps).
    • Gemini CLI Setup: Follow the Gemini CLI setup guide for client-specific configuration.

  12. Connect the ROS MCP Server to the image system

    main

    Once your ROS2 camera system is running and topics are visible (e.g., /image or /camera/camera/color/image_raw), start the MCP server using HTTP transport to allow an AI assistant to interact with the feed.

    # From the project root
cd /path/to/ros-mcp-server
export MCP_TRANSPORT=http
uv run server.py