ROS 2 MCP Server

A Model Context Protocol (MCP) server for ROS 2, enabling AI assistants like GitHub Copilot to introspect and interact with ROS 2 systems.

Features

The ROS 2 MCP Server provides 30+ tools for comprehensive ROS 2 system interaction:

• Node Management: List and inspect running nodes

• Topic Operations: List, echo, publish, and get topic information

• Service Operations: List services, inspect types, and call services

• Parameter Management: List, get, and set node parameters

• Action Operations: List actions, get info, and send goals

• Bag Operations: Record, play, and inspect bag files

• Interface Inspection: List and show message/service/action definitions

• Package Management: List packages, executables, and manifests

• Launch Operations: List and execute launch files with parameters

• Lifecycle Management: Control lifecycle nodes and transitions

• Diagnostics: Run system health checks with ros2 doctor

Installation

Quick Install

git clone https://github.com/ranch-hand-robotics/rde-mcp-ros-2.git
cd rde-mcp-ros-2
./install.sh

For detailed installation instructions including platform-specific configuration, see INSTALLATION.md.

Requirements

• ROS 2: Humble, Iron, Jazzy, or later

• Python: 3.8 or later

• Operating System: Linux (Ubuntu recommended), macOS, or Windows with WSL2

Installation

Option 1: Install from Source (Development)

# Clone the repository
git clone https://github.com/ranch-hand-robotics/rde-mcp-ros-2.git
cd rde-mcp-ros-2

# Install in editable mode
pip install -e .

Option 2: Install from GitHub (Coming Soon)

# Install via copilot CLI (planned)
gh copilot plugin install ranch-hand-robotics/rde-mcp-ros-2

ROS 2 Environment Setup

The server requires ROS 2 to be sourced in your environment. Add to your ~/.bashrc:

# Replace 'humble' with your ROS 2 distro
source /opt/ros/humble/setup.bash

Or source it before running:

source /opt/ros/<distro>/setup.bash
rde-mcp-ros2

Usage

Configuring Your AI Assistant

The MCP server uses stdio (standard input/output) transport, which means it's launched automatically by your AI tool when needed. No need to start a separate server!

The server works with:

• VS Code + GitHub Copilot - See examples/README.md

• GitHub Copilot CLI - See INSTALLATION.md

• Claude Desktop - See INSTALLATION.md

Quick config for VS Code (.vscode/mcp.json):

{
  "servers": {
    "ros2": {
      "command": "rde-mcp-ros2",
      "args": []
    }
  }
}

The server will be automatically started by the AI assistant when you ask ROS 2 questions!

Optional: Running in SSE Mode

If you need to run the server as a standalone HTTP server (for remote access or debugging):

# Start in SSE mode
rde-mcp-ros2 --transport sse --port 3002

# Or use the wrapper
./run-server.sh --transport sse

Then configure your client to use SSE:

{
  "servers": {
    "ros2": {
      "type": "sse",
      "url": "http://localhost:3002/sse"
    }
  }
}

Example Interactions

Once configured, ask your AI assistant:

• "What ROS 2 nodes are currently running?"

• "Show me the topics being published"

• "What's the current value of the /robot/speed parameter?"

• "Call the /reset_simulation service"

• "Record a bag file of all sensor topics for 30 seconds"

• "What packages are installed in my ROS 2 workspace?"

For more detailed examples, see examples/USAGE_EXAMPLES.md.

Documentation

• INSTALLATION.md - Detailed installation and configuration guide

• examples/README.md - Configuration examples for different platforms

• examples/USAGE_EXAMPLES.md - Real-world usage scenarios

• mcp-manifest.yaml - Full server capabilities manifest

Development

Setting Up Development Environment

# Clone and enter directory
git clone https://github.com/ranch-hand-robotics/rde-mcp-ros-2.git
cd rde-mcp-ros-2

# Install with dev dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest

# Format code
black src/
ruff check src/

Debugging

Use SSE mode for easier debugging:

1. Run the server directly:

source /opt/ros/<distro>/setup.bash
python src/rde_mcp_ros2/server.py

2. Configure VS Code to connect via SSE (see .vscode/mcp.json above)

3. Watch logs in the terminal where the server is running

Project Structure

rde-mcp-ros-2/
├── src/
│   └── rde_mcp_ros2/
│       ├── __init__.py
│       └── server.py          # Main MCP server implementation
├── pyproject.toml             # Package configuration
├── requirements.txt           # Python dependencies
├── README.md
└── LICENSE

Contributing

Contributions are welcome! Please:

1. Fork the repository

2. Create a feature branch (git checkout -b feature/amazing-feature)

3. Commit your changes (git commit -m 'Add amazing feature')

4. Push to the branch (git push origin feature/amazing-feature)

5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

Developed by Ranch Hand Robotics

Links

• GitHub Repository

• Model Context Protocol Documentation

• ROS 2 Documentation