How to add ROS MCP Server to Windsurf

Connect Claude, GPT, and Gemini to ROS/ROS 2 robots via rosbridge, with no changes to robot source code. Paste the config into ~/.codeium/windsurf/mcp_config.json and restart Windsurf.

Last updated June 14, 2026 · 1.3k★ · stdio · no auth

Windsurf config for ROS MCP Server

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

{
  "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.

Setup steps

1Open Windsurf → Cascade → the hammer/MCP icon → Configure (or edit ~/.codeium/windsurf/mcp_config.json).
2Paste the ROS MCP Server config below.
3Fill in placeholder secrets, then save.
4Click Refresh in the MCP panel.
5ROS MCP Server's tools become available to Cascade.

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)

What ROS MCP Server can do in Windsurf

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.

Security

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 + Windsurf FAQ

Where is the Windsurf config file?

Windsurf reads MCP servers from ~/.codeium/windsurf/mcp_config.json. Paste the ROS MCP Server config there under the "mcpServers" key and restart the client.

Is ROS MCP Server safe to use with Windsurf?

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.

View repo Full ROS MCP Server page