ROS MCP Server

Connect Claude, GPT, and Gemini to ROS/ROS 2 robots via rosbridge, with no changes to robot source code.

Unverified

stdio (local)

No auth

Python

View repo 1.3k Website

Add to your client

Copy the config for your MCP client and paste it into its config file.

Install / run

claude mcp add ros-mcp -- uvx ros-mcp --transport=stdio

Paste into ~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "uvx",
      "args": [
        "ros-mcp",
        "--transport=stdio"
      ]
    }
  }
}

Requires `uv` (the Python package runner). Install it from https://docs.astral.sh/uv/ if `uvx` is not found.

Step-by-step guides: Add to Claude Desktop · Add to Cursor · Add to Windsurf

Before you start

An MCP-compatible AI client (Claude Code, Codex CLI, Gemini CLI, Claude Desktop, ChatGPT, Cursor, etc.)
An account with an AI provider (e.g., Claude, OpenAI, Gemini)
uv / uvx installed on your machine (curl -LsSf https://astral.sh/uv/install.sh | sh)
Python 3.10+ and pip 23.0+
ROS or ROS 2 installed on the robot's machine
rosbridge_server installed and running on the robot (ros-<distro>-rosbridge-server, default WebSocket port 9090)
Both machines on the same local network (or connected via VPN)

About ROS MCP Server

ROS MCP Server is an MCP server that lets any MCP-compatible AI assistant (Claude, GPT, Gemini, and others) interact with a ROS or ROS 2 robot through the rosbridge WebSocket interface, without modifying the robot's source code. It exposes 31 tools for discovering and using topics, services, actions, nodes, and parameters, plus image analysis and robot specification lookup. The default stdio transport launches the server automatically via the AI client; a streamable-http transport is available for remote/multi-client setups. The robot side only needs rosbridge running.

Tools & capabilities (30)

connect_to_robot

Connect the MCP server to a robot's rosbridge endpoint by IP address (and optional port).

ping_robots

Test network connectivity to a robot's IP and rosbridge port to confirm reachability.

get_topics

Discover all ROS topics currently available on the robot.

get_topic_type

Get the message type of a specific topic.

get_topic_details

Get detailed information about a topic, including publishers/subscribers and type.

get_message_details

Inspect the full structure/fields of a given ROS message type (including custom types).

subscribe_once

Subscribe to a topic and return a single latest message.

subscribe_for_duration

Subscribe to a topic for a set duration and collect messages over that window.

publish_once

Publish a single message to a topic with a given message type and payload.

publish_for_durations

Publish a message to a topic repeatedly for a specified duration (e.g., continuous velocity commands).

get_services

Discover all ROS services available on the robot.

get_service_type

Get the type of a specific service.

get_service_details

Get detailed request/response structure for a service (including custom types).

call_service

Call a ROS service with the given request payload and return the response.

get_nodes

Discover all ROS nodes currently running on the robot.

get_node_details

Inspect a node's published/subscribed topics, services, and other details.

get_parameter

Get the value of a single ROS 2 parameter (ROS 2 only).

set_parameter

Set a ROS 2 parameter to a given value (ROS 2 only).

has_parameter

Check whether a given ROS 2 parameter exists (ROS 2 only).

delete_parameter

Delete a ROS 2 parameter (ROS 2 only).

get_parameters

List parameters for a given node (ROS 2 only).

get_parameter_details

Get detailed information about a ROS 2 parameter (ROS 2 only).

get_actions

Discover all ROS 2 actions available on the robot (ROS 2 only).

get_action_details

Get the goal/result/feedback structure of an action (ROS 2 only).

get_action_status

Get the current status of an action by name (ROS 2 only).

cancel_action_goal

Cancel a running action goal by action name and goal id (ROS 2 only).

view_saved_image

View/analyze an image captured from an image topic (image analysis).

get_verified_robot_spec

Load a verified robot specification by name from the bundled robot specs.

get_verified_robots_list

List the available verified robot specifications.

detect_ros_version

Detect whether the connected robot is running ROS 1 or ROS 2.

When to use it

Control a robot with natural language — e.g. 'Make the robot move forward' or 'Grab a Coke from the fridge and go to the living room'.
Diagnose hardware on a production robot — let the AI discover custom topics/services, run tests, and report root cause from technician manuals.
Explore an unfamiliar ROS system by asking what topics, services, nodes, and actions are available and inspecting their types.
Subscribe to sensor topics (e.g. /odom) and have the AI read and summarize the latest messages.
Drive robots in simulation (turtlesim, Unitree Go2 in NVIDIA Isaac Sim, Gazebo) without a physical robot.

Security notes

The MCP server connects to a robot's rosbridge WebSocket (default port 9090) and can both observe and control the robot — including publishing to topics, calling services, executing actions, and setting parameters. Restrict network exposure of rosbridge (do not expose port 9090 to untrusted networks; use a VPN for remote access). The HTTP transport defaults to host 127.0.0.1; binding to 0.0.0.0 exposes the server to the local network without authentication.

ROS MCP Server FAQ

Do I need to change my robot's source code?

No. You only need to add and launch the rosbridge node in your existing ROS setup; the MCP server connects to it over WebSocket.

Which ROS versions are supported?

Both ROS 2 (Jazzy, Humble, and others) and ROS 1 distros. Some tools (parameters and actions) are ROS 2 only.

How do I install it for Claude Code?

Install uv, then run `claude mcp add ros-mcp -- uvx ros-mcp --transport=stdio`. Verify with `claude mcp list` and restart Claude Code if the server isn't found.

Can the AI client and robot run on different machines?

Yes. They should be on the same local network (or connected via VPN). Make sure the rosbridge port (default 9090) isn't blocked by a firewall. For remote/multi-client access you can run the server with the streamable-http transport (e.g. `uvx ros-mcp --transport streamable-http --host 0.0.0.0 --port 9000`).

Does it require an API key or authentication?

No. The MCP server itself needs no API key; it connects to rosbridge directly. You only need an account with your AI provider for the client.

#ros #ros2 #robotics #rosbridge #robot-control #mcp #fastmcp

Alternatives to ROS MCP Server

Compare all alternatives →

Playwright MCP Server

Developer Tools

24k

Microsoft's official browser-automation MCP using Playwright's accessibility tree (no vision model).

Featured

Verified

stdio (local)

No auth

TypeScript

12 tools

Updated 13 days agoRepo

Context7 MCP Server

Developer Tools

28k

Up-to-date, version-specific library documentation injected into your coding agent.

Verified

stdio (local)

API key

TypeScript

2 tools

Updated 17 days agoRepo

Serena

Developer Tools

12k

LSP-powered coding agent toolkit: semantic symbol search, references and structural edits.

Verified

stdio (local)

No auth

Python

11 tools

Updated 15 days agoRepo

Compare ROS MCP Server with:

vs Playwright MCP Server vs Context7 MCP Server vs Serena vs Mobile MCP