Installation Guide

⚠️ Prerequisite: You need either ROS installed locally on your machine OR access over the network to a robot/computer with ROS installed. This MCP server connects to ROS systems on a robot, so a running ROS environment is required.

Installation includes the following steps:

Install the MCP server
- Clone this repository
- Install uv (Python virtual environment manager)
Install and configure the Language Model Client
- Install any language model client (We demonstrate with Claude Desktop)
- Configure the client to run the MCP server and connect automatically on launch.
Install and launch Rosbridge

Below are detailed instructions for each of these steps.

1. Install the MCP server (On the host machine where the LLM will be running)

1.1. Clone the Repository

git clone https://github.com/robotmcp/ros-mcp-server.git

⚠️ 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.

Note the absolute path to the cloned directory — you'll need this later when configuring your language model client.

1.2. Install UV (Python Virtual Environment Manager)

You can install uv using one of the following methods:

Option A: Shell installer

curl -LsSf https://astral.sh/uv/install.sh | sh

Option B: Using pip

pip install uv

2. Install and configure a Language Model Client

Any LLM client that supports MCP can be used. We use Claude Desktop for testing and development.

2.1. Download Claude Desktop

Linux (Ubuntu)

Follow the installation instructions from the community-supported claude-desktop-debian

MacOS

Download from claude.ai

Windows (Using WSL)

This will have Claude running on Windows and the MCP server running on WSL. We assume that you have cloned the repository and installed UV on your WSL

Download from claude.ai

2.2. Configure Claude Desktop to launch the MCP server

Linux (Ubuntu)

Locate and edit the claude_desktop_config.json file:
(If the file does not exist, create it)

~/.config/Claude/claude_desktop_config.json

Add the following to the "mcpServers" section of the JSON file
Make sure to replace <ABSOLUTE_PATH> with the full absolute path to your ros-mcp-server folder (note: ~ for home directory may not work in JSON files):

{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/<ABSOLUTE_PATH>/ros-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

MacOS

Locate and edit the claude_desktop_config.json file:
(If the file does not exist, create it)

~/Library/Application\ Support/Claude/claude_desktop_config.json

Add the following to the "mcpServers" section of the JSON file
Make sure to replace <ABSOLUTE_PATH> with the full absolute path to your ros-mcp-server folder (note: ~ for home directory may not work in JSON files):

{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "uv",
      "args": [
        "--directory",
        "/<ABSOLUTE_PATH>/ros-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

Windows (Using WSL)

Locate and edit the claude_desktop_config.json file:
(If the file does not exist, create it)

~/.config/Claude/claude_desktop_config.json

Add the following to the "mcpServers" section of the JSON file
Make sure to replace <ABSOLUTE_PATH> with the full absolute path to your ros-mcp-server folder (note: ~ for home directory may not work in JSON files):
Set the full WSL path to your uv installation (e.g., /home/youruser/.local/bin/uv)
Use the correct WSL distribution name (e.g., "Ubuntu-22.04")

{
  "mcpServers": {
    "ros-mcp-server": {
      "command": "wsl",
      "args": [
        "-d", "Ubuntu-22.04",
        "/home/<YOUR_USER>/.local/bin/uv",
        "--directory",
        "/<ABSOLUTE_PATH>/ros-mcp-server",
        "run",
        "server.py"
      ]
    }
  }
}

Alternate Configuration - HTTP Transport

The above configurations sets up the MCP server using the default STDIO transport layer, which launches the server as a plugin automatically on launching Claude.

It is also possible to configure the MCP server using the http transport layer, which configures Claude to connect to the MCP server when it is launched as a standalone application.

For HTTP transport, the configuration is the same across all platforms. First start the MCP server manually:

Linux/macOS/Windows(WSL):

cd /<ABSOLUTE_PATH>/ros-mcp-server
# Using command line arguments (recommended)
uv run server.py --transport streamable-http --host 127.0.0.1 --port 9000

# Or using environment variables (legacy)
export MCP_TRANSPORT=streamable-http
export MCP_HOST=127.0.0.1
export MCP_PORT=9000
uv run server.py

Then configure Claude Desktop to connect to the HTTP server (same for all platforms):

{
  "mcpServers": {
    "ros-mcp-server-http": {
      "name": "ROS-MCP Server (http)",
      "transport": "http",
      "url": "http://127.0.0.1:9000/mcp"
    }
  }
}

Comparison between default (STDIO) and HTTP Transport

STDIO Transport (Default)

Best for: Local development, single-user setups
Pros: Simple setup, no network configuration needed
Cons: MCP server and LLM/MCP client need to be running on the local machine.
Use case: Running MCP server directly with your LLM client

HTTP/Streamable-HTTP Transport

Best for: Remote access, multiple clients, production deployments
Pros: Network accessible, multiple clients can connect
Cons: Requires network configuration, MCP server needs to be run independently.
Use case: Remote robots, team environments, web-based clients

2.3. Test the connection

Launch Claude Desktop and check connection status.
The ros-mcp-server should be visible in your list of tools.

Troubleshooting

If the ros-mcp-server doesn't appear even after correctly configuring claude_desktop_config.json, try completely shutting down Claude Desktop using the commands below and then restarting it. This could be a Claude Desktop caching issue.

# Completely terminate Claude Desktop processes
pkill -f claude-desktop
# Or alternatively
killall claude-desktop

# Restart Claude Desktop
claude-desktop

3. Install and run rosbridge (On the target robot where ROS will be running)

ROS 1

3.1. Install `rosbridge_server`

This package is required for MCP to interface with ROS or ROS 2 via WebSocket. It needs to be installed on the same machine that is running ROS.

For ROS Noetic

sudo apt install ros-noetic-rosbridge-server

For other ROS Distros

sudo apt install ros-${ROS_DISTRO}-rosbridge-server

3.2. Launch rosbridge in your ROS environment:

roslaunch rosbridge_server rosbridge_websocket.launch

⚠️ Don’t forget to source your ROS workspace before launching, especially if you're using custom messages or services.

ROS 2

3.1. Install `rosbridge_server`

This package is required for MCP to interface with ROS or ROS 2 via WebSocket. It needs to be installed on the same machine that is running ROS.

For ROS 2 Humble

sudo apt install ros-humble-rosbridge-server

For other ROS Distros

sudo apt install ros-${ROS_DISTRO}-rosbridge-server

3.2. Launch rosbridge in your ROS environment:

ros2 launch rosbridge_server rosbridge_websocket_launch.xml

⚠️ Don’t forget to source your ROS workspace before launching, especially if you're using custom messages or services.

4. You're ready to go!

You can test out your server with any robot that you have running. Just tell your AI to connect to the robot using its target IP address. (Default is localhost, so you don't need to tell it to connect if the MCP server is installed on the same machine as your ROS)

✅ Tip: If you don't currently have any robots running, turtlesim is considered the 'hello world' robot for ROS to experiment with. It does not have any simulation dependencies such as Gazebo or IsaacSim.

For a complete step-by-step tutorial on using turtlesim with the MCP server and for more information on ROS and turtlesim, see our Turtlesim Tutorial.

If you have ROS already installed, you can launch turtlesim with the below command: ROS1:

rosrun turtlesim turtlesim_node

ROS2:

ros2 run turtlesim turtlesim_node

Example Commands

Natural language commands

Example:

Make the robot move forward.

Query your ROS system

Example:

What topics and services do you see on the robot?

5. Alternate Clients (ChatGPT, Gemini, Cursor)

Examples and setup instructions for other LLMs

3.2.1. Cursor IDE

For detailed Cursor setup instructions, see our Cursor Tutorial.

3.2.2. ChatGPT

For detailed ChatGPT setup instructions, see our ChatGPT Tutorial.

3.2.3. Google Gemini

For detailed Gemini setup instructions, see our Gemini Tutorial.

Custom MCP Client

3.2.1. Using the MCP Server Programmatically

You can also use the MCP server directly in your Python code:

from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def main():
    server_params = StdioServerParameters(
        command="uv",
        args=["--directory", "/path/to/ros-mcp-server", "run", "server.py"]
    )
    
    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            # Use the MCP server
            result = await session.call_tool("get_topics", {})
            print(result)

6. Troubleshooting

6.1. Common Issues

MCP Server Not Appearing in Client

Symptoms: The ros-mcp-server doesn't appear in your LLM client's tool list.

Solutions:

Check file paths: Ensure all paths in your configuration are absolute and correct
Restart client: Completely shut down and restart your LLM client
Check logs: Look for error messages in your LLM client's logs
Test manually: Try running the MCP server manually to check for errors:

cd /<ABSOLUTE_PATH>/ros-mcp-server
uv run server.py

Connection Refused Errors

Symptoms: "Connection refused" or "No valid session ID provided" errors.

Solutions:

Check ROS is running: Ensure ROS and rosbridge are running
Verify rosbridge port: Default is 9090, check if it's different
Test connectivity: Use the ping tool to test connection:

# Test if rosbridge is accessible
curl -I http://localhost:9090

Check firewall: Ensure firewall allows the rosbridge port

WSL-Specific Issues

Symptoms: Issues when running on Windows with WSL.

Solutions:

Check WSL distribution: Ensure you're using the correct WSL distribution name
Verify uv path: Check that the uv path in WSL is correct:

# In WSL
which uv

Test WSL connectivity: Ensure Windows can reach WSL services
Check WSL networking: For HTTP transport, use 0.0.0.0 instead of 127.0.0.1

HTTP Transport Issues

Symptoms: HTTP transport not working or connection timeouts.

Solutions:

Check command line arguments: Ensure the correct transport, host, and port are specified:

# Check available options
python server.py --help

# Example with custom settings
python server.py --transport http --host 0.0.0.0 --port 8080

Check environment variables (legacy): Ensure MCP_TRANSPORT, MCP_HOST, and MCP_PORT are set correctly
Verify port availability: Check if the port is already in use:

# Check if port is in use
netstat -tulpn | grep :9000

Test HTTP endpoint: Try accessing the HTTP endpoint directly:

curl http://localhost:9000

Check firewall: Ensure firewall allows the configured port

6.2. Debug Commands

# Test ROS connectivity
ros2 topic list  # For ROS 2
rostopic list   # For ROS 1

# Test rosbridge
curl -I http://localhost:9090

# Test MCP server manually
cd /<ABSOLUTE_PATH>/ros-mcp-server
uv run server.py

# Check processes
ps aux | grep rosbridge
ps aux | grep ros-mcp

6.3. Getting Help

If you're still having issues:

Check the logs: Look for error messages in your LLM client and MCP server logs
Test with turtlesim: Try the turtlesim tutorial to verify basic functionality
Open an issue: Create an issue on the GitHub repository with:
- Your operating system
- ROS version
- LLM client being used
- Error messages
- Steps to reproduce

---

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Installation Guide

1. Install the MCP server (On the host machine where the LLM will be running)

1.1. Clone the Repository

1.2. Install UV (Python Virtual Environment Manager)

2. Install and configure a Language Model Client

2.1. Download Claude Desktop

2.2. Configure Claude Desktop to launch the MCP server

STDIO Transport (Default)

HTTP/Streamable-HTTP Transport

2.3. Test the connection

3. Install and run rosbridge (On the target robot where ROS will be running)

3.1. Install `rosbridge_server`

3.2. Launch rosbridge in your ROS environment:

3.1. Install `rosbridge_server`

3.2. Launch rosbridge in your ROS environment:

4. You're ready to go!

Natural language commands

Query your ROS system

5. Alternate Clients (ChatGPT, Gemini, Cursor)

3.2.1. Cursor IDE

3.2.2. ChatGPT

3.2.3. Google Gemini

3.2.1. Using the MCP Server Programmatically

6. Troubleshooting

6.1. Common Issues

6.2. Debug Commands

6.3. Getting Help

FilesExpand file tree

installation.md

Latest commit

History

installation.md

File metadata and controls

Installation Guide

1. Install the MCP server (On the host machine where the LLM will be running)

1.1. Clone the Repository

1.2. Install UV (Python Virtual Environment Manager)

2. Install and configure a Language Model Client

2.1. Download Claude Desktop

2.2. Configure Claude Desktop to launch the MCP server

STDIO Transport (Default)

HTTP/Streamable-HTTP Transport

2.3. Test the connection

3. Install and run rosbridge (On the target robot where ROS will be running)

3.1. Install rosbridge_server

3.2. Launch rosbridge in your ROS environment:

3.1. Install rosbridge_server

3.2. Launch rosbridge in your ROS environment:

4. You're ready to go!

Natural language commands

Query your ROS system

5. Alternate Clients (ChatGPT, Gemini, Cursor)

3.2.1. Cursor IDE

3.2.2. ChatGPT

3.2.3. Google Gemini

3.2.1. Using the MCP Server Programmatically

6. Troubleshooting

6.1. Common Issues

6.2. Debug Commands

6.3. Getting Help

3.1. Install `rosbridge_server`

3.1. Install `rosbridge_server`