Skip to content

README.md

Latest commit

 

History

History
318 lines (239 loc) · 8.82 KB

README.md

File metadata and controls

318 lines (239 loc) · 8.82 KB

Cursor Desktop with ROS-MCP-Server

Prerequisites

Prepare host machine (MCP Server)

  • Installation of Cursor Desktop. Download here.
  • Installation of WSL on Windows

Prepare target robot (ROS)

  • Installation of Ubuntu or WSL (Windows Subsystem for Linux) on Windows.
  • Installation of ROS or ROS2. Test if ROS is installed by running Turtlesim. If you are not sure, follow, this tutorial. See here.

Tutorial

Quick Start (For Experienced Users)

  1. Install dependencies: curl -LsSf https://astral.sh/uv/install.sh | sh
  2. Clone repository: cd ~ && git clone https://github.com/robotmcp/ros-mcp-server.git && cd ros-mcp-server
  3. Configure Cursor: Add stdio transport to mcp.json (see Option 2 below)
  4. Start ROS: ros2 launch rosbridge_server rosbridge_websocket_launch.xml & ros2 run turtlesim turtlesim_node
  5. Test: Ask Cursor to "List ROS topics"

1.1 Installation on Host Machine

Install dependencies

  • Install uv using one of the following methods:

    Option A: PowerShell (Windows) 
     winget install --id=astral-sh.uv -e

    or

     pip install uv
    Option B: WSL (Linux) 
     curl -LsSf https://astral.sh/uv/install.sh | sh

    or (not recommended)

     pip install uv

    or (not recommended)

     sudo snap install --classic astral-uv

Install ROS-MCP Server

  • On your Host Machine, clone the repository and navigate to the ROS-MCP Server folder.
cd ~
git clone https://github.com/robotmcp/ros-mcp-server.git
cd ros-mcp-server

⚠️ WSL Users: Clone the repository in your WSL home directory (e.g., /home/username/) instead of the Windows filesystem mount (e.g., /mnt/c/Users/username/). Using the native Linux filesystem provides better performance and avoids potential permission issues.

1.4 Connect ROS-MCP to Cursor

  • Open Cursor Desktop
  • Navigate to Settings (gear icon top right)
  • Open MCP > New MCP Server
  • Modify the mcp.json as follows:

Option 1: HTTP Transport (Network-based)

Note: For HTTP transport, you need to manually start the MCP server first.

  • Start the MCP server in WSL:
wsl
cd ros-mcp-server
uv run server.py --transport http
  • Configure Cursor with the following:
{
  "mcpServers": {
    "ros-mcp-server-http": {
      "name": "ROS-MCP Server (http)",
      "transport": "http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

Option 2: Stdio Transport (Direct WSL execution) - Recommended

Benefits of stdio transport:

  • No need to manually start the server
  • Direct communication with WSL
  • More reliable and faster
  • Automatic server management

Important Configuration Notes:

  • Make sure to clone the ros-mcp-server folder to your /home/<YOUR_USER> directory (note: ~ for home directory may not work in JSON files)
"/home/<YOUR_USER>/ros-mcp-server" # Recommended: WSL/Linux home directory

  • Avoid using /mnt/c/Users/<YOUR_USER>/ paths - these point to the Windows filesystem which can cause performance issues and permission problems

  • Use the correct WSL distribution name (e.g., "Ubuntu" or "Ubuntu-22.04")

  • Make sure to replace <YOUR_USER> with your actual WSL username

  • Ensure uv is installed at /home/<YOUR_USER>/.local/bin/uv, if not modify the installation directory (which uv can help locate.)

{
  "mcpServers": {
    "ros-mcp-server": {
      "name": "ROS-MCP Server (stdio)",
      "transport": "stdio",
      "command": "wsl",
      "args": [
        "-d", "Ubuntu",
        "/home/<YOUR_USER>/.local/bin/uv",
        "--directory",
        "/home/<YOUR_USER>/ros-mcp-server",
        "run",
        "server.py"
      ]
  }
}

Option 3: Both HTTP and Stdio (Complete Configuration)

You can copy-paste the mcp.json in this folder and modify <YOUR_USER> accordingly:

{
  "mcpServers": {
    "ros-mcp-server-http": {
      "name": "ROS-MCP Server (http)",
      "transport": "http",
      "url": "http://127.0.0.1:9000/mcp"
    },
    "ros-mcp-server-stdio": {
      "name": "ROS-MCP Server (stdio)",
      "transport": "stdio",
      "command": "wsl",
      "args": [
        "-d", "Ubuntu",
        "/home/<YOUR_USER>/.local/bin/uv",
        "--directory",
        "/home/<YOUR_USER>/ros-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

1.5 Run ROS on Target Machine

In WSL, launch rosbridge and turtlesim

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

or

launch_ros.sh

1.6 Test Your Setup

Once everything is configured, test your connection:

  1. Start a new chat in Cursor

  2. Try a simple ROS command like:

    • "List all available ROS topics"
    • "Show me the current ROS node information"
    • "What robots are available in the specifications?"

  3. Verify the connection - you should see ROS-related responses from the MCP server

2. Troubleshooting

Common Issues

MCP Server not connecting:

  • Verify WSL is running: wsl --list --verbose
  • Check if uv is installed: wsl -- which uv
  • Ensure the ros-mcp-server directory exists in WSL

ROS Bridge connection failed:

  • Make sure ROS is running: ros2 node list
  • Verify rosbridge is active: ros2 launch rosbridge_server rosbridge_websocket_launch.xml
  • Check if port 9090 is available

Stdio transport not working:

  • Verify the WSL distribution name is correct
  • Check if the uv path is accurate: /home/<YOUR_USER>/.local/bin/uv
  • Ensure the ros-mcp-server directory is in the correct location /home/<YOUR_USER>/ros-mcp-server

Debug Commands

# Test WSL connection
wsl --list --verbose

# Test uv installation
wsl -- which uv

# Test ROS installation
wsl -- ros2 node list

# Test rosbridge
wsl -- ros2 topic list

3. Usage Examples

Once connected, you can use natural language to interact with your ROS system:

  • "Move the turtle forward" - Controls turtlesim
  • "What topics are currently publishing?" - Lists active topics
  • "Show me the robot specifications" - Displays available robot configs
  • "Connect to robot at IP 192.168.1.100" - Connects to remote robot
  • "Take a picture with the camera" - Captures camera data

4. Advanced Configuration

Environment Variables

You can customize the MCP server behavior with these environment variables:

# ROS Bridge settings
export ROSBRIDGE_IP="127.0.0.1"  # Default: localhost
export ROSBRIDGE_PORT="9090"     # Default: 9090

# MCP Transport settings
export MCP_TRANSPORT="streamable-http"  # For ChatGPT: streamable-http
export MCP_TRANSPORT="stdio"            # For Cursor: stdio (recommended)
export MCP_HOST="127.0.0.1"             # For HTTP transport
export MCP_PORT="9000"                  # For HTTP transport

Custom Robot Specifications

Add your own robot configurations in utils/robot_specifications/:

# utils/robot_specifications/my_robot.yaml
name: "My Custom Robot"
ip: "192.168.1.100"
port: 9090
description: "My custom robot configuration"

Multiple Robot Support

You can connect to multiple robots by switching configurations:

# Connect to different robots
export ROSBRIDGE_IP="192.168.1.100"  # Robot 1
export ROSBRIDGE_IP="192.168.1.101"  # Robot 2

5. FAQ

Q: Can I run multiple MCP servers? A: Yes, you can configure multiple servers in your mcp.json file.

Q: Is stdio transport faster than HTTP? A: Yes, stdio transport is generally faster and more reliable as it eliminates network overhead.

Q: Can I use this without WSL? A: The current setup requires WSL for ROS compatibility on Windows. Linux and macOS users can run directly.

6. Tested Configurations

Host Machine

  • Windows 11
  • WSL with Ubuntu 22.04
  • Cursor Desktop

Target Machine

  • WSL with Ubuntu 22.04
  • ROS 2 Jazzy

7. Support and Contributing

Getting Help

  • Issues: Report bugs and request features on GitHub Issues
  • Documentation: Check the main README.md for additional information
  • Community: Join discussions in the project's GitHub Discussions

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

  • Setting up a development environment
  • Code style guidelines
  • Submitting pull requests
  • Testing procedures