MCP Directory

How to add ROS MCP to Claude Desktop

Control robots in ROS2 environments with natural language via topics, services, and actions. Paste the config into ~/Library/Application Support/Claude/claude_desktop_config.json and restart Claude Desktop.

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

Claude Desktop 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 Claude Desktop → Settings → Developer → Edit Config (this opens ~/Library/Application Support/Claude/claude_desktop_config.json).
  2. 2Paste the ROS MCP config below under the top-level "mcpServers" key.
  3. 3Fill in any placeholder secrets (API keys, paths) in the snippet.
  4. 4Save the file, then fully quit and reopen Claude Desktop.
  5. 5Open a chat and confirm ROS MCP's tools appear under the 🔌 tools menu.

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 Claude Desktop

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 + Claude Desktop FAQ

Where is the Claude Desktop config file?

Claude Desktop reads MCP servers from ~/Library/Application Support/Claude/claude_desktop_config.json. Paste the ROS MCP config there under the "mcpServers" key and restart the client.

Is ROS MCP safe to use with Claude Desktop?

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