robotmcp--ros-mcp-server/examples/7_cursor/README.md

# Cursor Desktop with ROS-MCP-Server

> **See also:** The [Cursor setup guide](../../docs/install/clients/cursor.md) in the main installation docs for a streamlined setup.

## Prerequisites

### Prepare host machine (MCP Server)

* Installation of Cursor Desktop. Download [here](https://cursor.com/downloads).
* 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](https://wiki.ros.org/ROS/Tutorials).

# 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`](https://github.com/astral-sh/uv) using one of the following methods:

    <details>
	<summary><strong>Option A: PowerShell (Windows)</strong></summary>

	```bash
	winget install --id=astral-sh.uv -e
	```
	or
	```bash
	pip install uv
	```
	
	</details>

 	<details>
	<summary><strong>Option B: WSL (Linux) </strong></summary>

	```bash
	curl -LsSf https://astral.sh/uv/install.sh | sh
	```
	or (not recommended)
	```bash
	pip install uv
	```
	or (not recommended)
	```bash
	sudo snap install --classic astral-uv
	```
	</details>



### Install ROS-MCP Server

*  On your Host Machine, clone the repository and navigate to the ROS-MCP Server folder.

```bash
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:
```bash
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`

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

or

```bash
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

```bash
# 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:

```bash
# 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/`:

```yaml
# 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:

```bash
# 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](https://github.com/robotmcp/ros-mcp-server/issues)
- **Documentation**: Check the main [README.md](../../README.md) for additional information
- **Community**: Join discussions in the project's GitHub Discussions

### Contributing
We welcome contributions! Please see our [Contributing Guide](../../docs/contributing.md) for details on:
- Setting up a development environment
- Code style guidelines
- Submitting pull requests
- Testing procedures