robotmcp--ros-mcp-server/examples/6_chatgpt

ChatGPT Desktop with ROS-MCP-Server

See also: The ChatGPT setup guide in the main installation docs for a streamlined setup.

Prerequisites

Prepare host machine (MCP Server)

• Installation of ChatGPT Desktop. Download here or Microsoft Store.
• Installation of WSL (Linux) or a terminal on macOS.

💡 macOS Users: You can run the MCP server and ngrok directly on macOS without WSL. For ROS2, use Docker (see 5_docker_turtlesim for a ready-made container) since ROS2 is not natively available on macOS.

Prepare target robot (ROS)

• Installation of Ubuntu, WSL (Windows Subsystem for Linux), or Docker (macOS).
• Installation of ROS or ROS2. Test if ROS is installed by running Turtlesim. If you are not sure, follow this tutorial [https://wiki.ros.org/ROS/Tutorials]

Tutorial

Quick Start (For Experienced Users)

1. Install dependencies: curl -LsSf https://astral.sh/uv/install.sh | sh and ngrok config add-authtoken <YOUR_AUTHTOKEN>
2. Clone repository: cd ~ && git clone https://github.com/robotmcp/ros-mcp-server.git && cd ros-mcp-server
3. Start MCP server: uv run server.py --transport streamable-http
4. Start ngrok tunnel: ngrok http --url=your-domain.ngrok-free.app 9000
5. Configure ChatGPT: Add connector with URL https://your-domain.ngrok-free.app/mcp
6. Start ROS: ros2 launch rosbridge_server rosbridge_websocket_launch.xml & ros2 run turtlesim turtlesim_node
7. Test: Ask ChatGPT 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
  

  Option C: macOS

  Using Homebrew:

  brew install uv
  

  or curl:

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

  or pip:

  pip3 install uv
  

  💡 Note: If installed via pip, you may need to add ~/Library/Python/3.x/bin to your PATH.

• Install ngrok using one of the following methods:

  Option A: PowerShell (Windows)

  Install from Microsoft Store or from here

  Option B: WSL (Linux)

  Using Apt:

  curl -sSL https://ngrok-agent.s3.amazonaws.com/ngrok.asc \\
    | sudo tee /etc/apt/trusted.gpg.d/ngrok.asc >/dev/null \\
    \&\& echo "deb https://ngrok-agent.s3.amazonaws.com bookworm main" \\
    | sudo tee /etc/apt/sources.list.d/ngrok.list \\
    \&\& sudo apt update \\
    \&\& sudo apt install ngrok
  

  or snap:

  sudo snap install ngrok
  

  Option C: macOS

  Using Homebrew:

  brew install ngrok
  

  or download directly from ngrok.com/download.

• Login or create your account at ngrok

• Navigate to Your Authtoken

• Copy your Authtoken to clipboard <YOUR_AUTHTOKEN>

• Activate ngrok with the following command, replacing <YOUR_AUTHTOKEN>:

ngrok config add-authtoken <YOUR_AUTHTOKEN>

• Obtain a static domain in ngrok by navigating to Domains

• It should look be something like: abc123-xyz789.ngrok-free.app

• Save the ROS-MCP url domain, replacing it with yours.

  Option A: PowerShell (Windows)

  $env:MCP_DOMAIN=abc123-xyz789.ngrok-free.app
  

  Option B: WSL (Linux)

  export MCP_DOMAIN=abc123-xyz789.ngrok-free.app
  

  Option C: macOS (zsh)

  export MCP_DOMAIN=abc123-xyz789.ngrok-free.app
  

  Add to ~/.zshrc for persistence.

• In WSL (Linux) or macOS, consider adding all your MCP variables to .bashrc or ~/.zshrc

export MCP_HOST=127.0.0.1
export MCP_PORT=9000
export MCP_DOMAIN=abc123-xyz789.ngrok-free.app

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.2 Run ROS-MCP Server

• Run the ROS-MCP using one of the following:

  Option A: PowerShell (Windows)

  In PowerShell, set the tranport protocol:

  $env:MCP_TRANSPORT="streamable-http" 
  

  If you installed uv used the following:

  
  uv run server.py --transport streamable-http
  

  Otherwise you have to install all the dependencies manually and run:

  python server.py --transport streamable-http
  

  Option B: WSL (Linux)

  Open WSL

  Run the following:

  uv run server.py --transport streamable-http
  

  or

  cd scripts
  launch_mcp_server.sh
  

  Option C: macOS

  uv run server.py --transport streamable-http
  

  Or if uv was installed via pip and is not in your PATH:

  python3 -m uv run server.py --transport streamable-http
  

• By default, the server should start at 127.0.0.1:9000, you can set MCP_HOST and MCP_PORT variables as needed

1.3 Tunnel ROS-MCP Server

• On your host machine, launch ngrok with one of the following:

  Option A: PowerShell (Windows)

  In PowerShell, set the local port to tunnel:

  $env:MCP_PORT=9000
  $env:MCP_DOMAIN=<YOUR_DOMAIN>
  

  Run ngrok to tunnel your ROS-MCP server.

  ngrok http --url=$env:MCP_DOMAIN $env:MCP_PORT
  

  Option B: WSL (Linux)

  In WSL, set the local port to tunnel:

  export MCP_PORT=9000
  export MCP_DOMAIN=<YOUR_DOMAIN>
  

  Run ngrok to tunnel your ROS-MCP server.

  ngrok http --url=${MCP_DOMAIN} ${MCP_PORT}
  

  Or you can also launch:

  launch_mcp_tunnel.sh
  

  Option C: macOS

  export MCP_PORT=9000
  export MCP_DOMAIN=<YOUR_DOMAIN>
  ngrok http --url=${MCP_DOMAIN} ${MCP_PORT}
  

• Once you launch ngrok, verify your public url domain, it should be the same as MCP_DOMAIN.

  https://your-domain.ngrok-free.app -> http://localhost:9000
  

1.4 Connect ROS-MCP to ChatGPT

• Open ChatGPT Desktop

• Navigate to Settings (Bottom Left)

• Open Connectors

• Create and fill the following:

  • Name: ROS-MCP Server
  • Description: An MCP Server to connect with ROS/ROS2
  • MCP Server URL: https://your-domain.ngrok-free.app/mcp (don't forget to replace with your domain and add the /mcp)
  • Authentication: No authentication
  • I trust this application

• In ChatGPT, start a new Chat, navigate to + > Developer Mode > Add sources > Activate ROS-MCP Server

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

💡 macOS Users: ROS2 is not natively available on macOS. Use the Docker-based approach from 5_docker_turtlesim:

cd ../5_docker_turtlesim
docker compose up turtlesim

This starts rosbridge on port 9090 and turtlesim in a container. The MCP server on your host connects to it automatically. Note that the turtlesim GUI requires X11 forwarding (install XQuartz), but rosbridge works without it.

1.6 Test Your Setup

Once everything is configured, test your connection:

1. Start a new chat in ChatGPT Desktop

2. Activate the ROS-MCP Server in Developer Mode

3. 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?"

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

2. Troubleshooting

Common Issues

MCP Server not connecting:

• Verify the server is running: Check if uv run server.py --transport streamable-http is active
• Check if ngrok tunnel is working: Visit your ngrok URL in browser
• Ensure the server is accessible at http://127.0.0.1:9000/mcp

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

Ngrok tunnel issues:

• Verify your authtoken is set: ngrok config check
• Check if your domain is active: Visit ngrok dashboard at http://127.0.0.1:4040/status
• Ensure port 9000 is not blocked by firewall

ChatGPT connector not working:

• Verify the MCP Server URL includes /mcp at the end
• Check if "I trust this application" is checked
• Restart ChatGPT Desktop after adding the connector

macOS-specific issues:

• No ROS2 natively: Use Docker — see 5_docker_turtlesim or a Linux VM
• Turtlesim GUI not displaying: Install XQuartz (brew install --cask xquartz), log out/in, then run xhost +localhost before launching Docker. Alternatively, run headless — rosbridge still works without the GUI.
• uv not found after pip3 install uv: Add ~/Library/Python/3.x/bin to your PATH, or use curl -LsSf https://astral.sh/uv/install.sh | sh instead
• Port 9000 already in use: Check with lsof -i :9000 and kill the conflicting process

Debug Commands

# Test server locally
curl http://127.0.0.1:9000/mcp

# Test ngrok tunnel
curl https://your-domain.ngrok-free.app/mcp

# Test ROS installation (WSL)
wsl -- ros2 node list

# Test ROS installation (macOS Docker)
docker exec ros2-turtlesim ros2 node list

# Test rosbridge (WSL)
wsl -- ros2 topic list

# Test rosbridge (macOS Docker)
docker exec ros2-turtlesim ros2 topic list

# Check ngrok status
ngrok api tunnels 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
• "Publish a velocity command" - Sends movement commands

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_HOST="127.0.0.1"             # For HTTP transport
export MCP_PORT="9000"                  # For HTTP transport

# Ngrok settings
export MCP_DOMAIN="your-domain.ngrok-free.app"  # Your ngrok domain

5. FAQ

Q: Do I need ngrok for local testing? A: For ChatGPT Desktop, yes. ChatGPT requires a public URL to connect to MCP servers.

Q: Can I use a different tunneling service? A: Yes, you can use any tunneling service that provides HTTPS URLs, but ngrok is recommended.

Q: Is the connection secure? A: The connection uses HTTPS through ngrok, but for production use, consider additional security measures.

Q: Can I run multiple MCP servers? A: Yes, you can configure multiple servers, but each needs its own ngrok tunnel and port.

Q: What if my ngrok domain changes? A: You'll need to update the MCP Server URL in ChatGPT Desktop settings.

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)

• Windows 11
• WSL with Ubuntu 22.04
• ChatGPT Desktop
• ngrok (free/paid)

Target Machine (Windows/WSL)

• WSL with Ubuntu 22.04
• ROS 2 Jazzy
• rosbridge_server

Host Machine (macOS)

• macOS (Apple Silicon / ARM64)
• Python 3.13, uv (via pip or Homebrew)
• MCP server: streamable-http on localhost:9000

Target Machine (macOS via Docker)

• Docker Desktop for Mac
• ROS 2 Humble in Docker container (5_docker_turtlesim)
• rosbridge_server on port 9090

Tested 2026-03-29: MCP server started on macOS, connected to rosbridge in Docker, successfully called MCP tools (connect_to_robot, get_topics, get_nodes, publish_once, call_service).

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