MCP Directory

How to add ROS MCP to Cursor

Control robots in ROS2 environments with natural language via topics, services, and actions. Paste the config into ~/.cursor/mcp.json and restart Cursor.

Last updated June 14, 2026 · 35★ · stdio · no auth

Cursor config for ROS MCP

git clone git@github.com:Yutarop/ros-mcp.git && cd ros-mcp && uv venv && source .venv/bin/activate && uv pip install -e .
{
  "mcpServers": {
    "ros-mcp": {
      "command": "uv",
      "args": [
        "--directory",
        "/ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-mcp",
        "run",
        "bash",
        "-c",
        "export ROS_LOG_DIR=/tmp && export ROS_DOMAIN_ID=${ROS_DOMAIN_ID:-YOUR_ROS_DOMAIN_ID} && source /opt/ros/humble/setup.bash && python3 /ABSOLUTE/PATH/TO/PARENT/FOLDER/ros-general.py"
      ]
    }
  }
}

Setup steps

  1. 1Open Cursor → Settings → MCP → Add new MCP server (or edit ~/.cursor/mcp.json directly).
  2. 2Paste the ROS MCP config below into the "mcpServers" object.
  3. 3Fill in placeholder secrets, then save.
  4. 4Cursor reloads MCP servers automatically — check Settings → MCP for a green status dot.
  5. 5Ask Cursor to use one of ROS MCP's tools to confirm it's connected.

Before you start

  • ROS2 Humble Hawksbill (other ROS2 distributions not guaranteed)
  • Claude Desktop (Linux/macOS/Windows)
  • Python 3.10+
  • websockets >= 15.0.1
  • uv package manager

What ROS MCP can do in Cursor

Topic Management

List, monitor, and publish to ROS2 topics.

Node Control

List and inspect running ROS2 nodes.

Service Interaction

Call ROS2 services with custom requests.

Action Support

Send goals to ROS2 actions.

GUI Integration

Launch ROS2 GUI tools (e.g. Gazebo, rqt_graph) via the WebSocket socket server.

Environment Debugging

Check ROS2 setup and configuration.

Process Management

Clean up running ROS2 processes.

Security

The companion socket server listens on localhost:8765 and launches local GUI processes (Gazebo, rqt_graph) on instruction from the MCP server. Run it only on a trusted local network; the MCP server can clean up / kill running ROS2 processes and publish to topics, so it has effective control over connected robots and simulators.

ROS MCP + Cursor FAQ

Where is the Cursor config file?

Cursor reads MCP servers from ~/.cursor/mcp.json. Paste the ROS MCP config there under the "mcpServers" key and restart the client.

Is ROS MCP safe to use with Cursor?

The companion socket server listens on localhost:8765 and launches local GUI processes (Gazebo, rqt_graph) on instruction from the MCP server. Run it only on a trusted local network; the MCP server can clean up / kill running ROS2 processes and publish to topics, so it has effective control over connected robots and simulators.

Which ROS2 distributions are supported?

The project has only been tested with ROS2 Humble Hawksbill. Compatibility with other ROS2 distributions is not guaranteed.

Why are there two servers?

The MCP server (ros-general.py) implements the protocol and maps language to ROS commands, while a separate socket server on localhost:8765 handles GUI operations like launching Gazebo or rqt_graph on the local display.

How do the MCP server and my machine communicate?

Both must be configured with the same ROS_DOMAIN_ID on the same local network to enable ROS node communication.

View repo Full ROS MCP page