# robotmcp/ros-mcp-server architecture

> Architecture diagram of the GitHub repository robotmcp/ros-mcp-server, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-09-15). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/robotmcp/ros-mcp-server
- Repository: https://github.com/robotmcp/ros-mcp-server

## Overview

##### Project type and purpose
- This is a middleware service (“ROS MCP Server”) that sits between Large Language Model (LLM) clients and ROS/ROS2-based robots. It provides bidirectional connectivity: translating natural-language commands into ROS messages, and streaming ROS data back to the LLM.

##### File structure
- Top-level artifacts:
- server.py – the entrypoint for the FastAPI/uvicorn-based MCP server
- utils/ – helper modules (network utilities, WebSocket manager)
- pyproject.toml – Python dependencies and project metadata
- examples/ – sample ROS1/ROS2 scenarios (Turtlesim, Gemini, Unitree, Docker setups)
- No frontend code: the client is any MCP-enabled LLM (Claude Desktop, ChatGPT plugin, Gemini, etc.)
- CI/CD workflows under .github/workflows for automated testing or deployment

##### README for additional insights
- Key components mentioned: LLM client, MCP server, ROS bridge node, ROS master, topics/services, sensor data streams.
- Technology stack: Python 3.10+, uvicorn (webserver), FastAPI (implied), websockets, rosbridge.

##### Main components and their interactions
a. LLM Client (Claude Desktop, ChatGPT plugin, Gemini, etc.)
- Opens a WebSocket/HTTP connection to the MCP Server
- Sends text-based commands; receives JSON messages describing ROS state and sensor data
b. MCP Server
- server.py launches a FastAPI app under uvicorn
- websocket_manager.py handles bidirectional JSON messaging
- network_utils.py manages low-level serialization/heartbeat, etc.
- Translates LLM requests into JSON-RPC calls over ROS bridge
- Manages subscriptions, publishes, service calls, parameter get/set
c. ROS Bridge Node (rosbridge_server)
- A ROS1/ROS2 node that exposes ROS master’s topic/service/parameter API over WebSocket or TCP
- Deployed on the target robot or simulation
d. ROS1/ROS2 Core
- Topic bus, service registry, parameter server – the heart of the robot’s runtime
e. Robot Hardware or Simulator
- Actual sensors/actuators (cameras, LIDAR, motors) in real or simulated environment (Isaac Sim)

##### Architectural patterns and design principles
- Microservice style: single responsibility for translation logic
- Adapter pattern: converting LLM JSON payloads to ROS bridge JSON-RPC and back
- Pub/Sub: subscribing to ROS topics for real-time updates
- Request/Response: invoking ROS services and returning results

##### Detail capture checklist
- Component names and purposes
- Data flow directions and protocols
- Key technologies and libraries
- Expandable extension points (utils, examples)
- Version-agnostic support (ROS1 & ROS2)
- Future features (Actions, permission controls)

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Layer 1: LLM Client
    subgraph "Layer 1: LLM Client"
        direction TB
        LLM["LLM Client<br/>(Claude, ChatGPT Plugin, Gemini)"]:::external
    end

    %% Layer 2: MCP Server
    subgraph "Layer 2: MCP Server (Middleware)" 
        direction TB
        Server["MCP Server<br/>Python, FastAPI, Uvicorn"]:::middleware
        WSManager["WebSocket Manager<br/>utils/websocket_manager.py"]:::middleware
        NetUtils["Network Utilities<br/>utils/network_utils.py"]:::middleware
        Config["pyproject.toml"]:::middleware
        subgraph "Examples (ROS Bridge & Simulation)" 
            direction TB
            Ex1["Turtlesim (ROS1)"]:::middleware
            Ex2["Gemini (ROS2)"]:::middleware
            Ex3["Limo Mobile Robot"]:::middleware
            Ex4["Unitree Go2 Robot"]:::middleware
            Ex5["Docker Turtlesim"]:::middleware
        end
        subgraph "CI/CD Workflows"
            direction TB
            CI1[".github/workflows/clone-trend.yml"]:::middleware
            CI2[".github/workflows/traffic-trend.yml"]:::middleware
        end
        subgraph "Documentation & Governance"
            direction TB
            Doc1["README.md"]:::docs
            Doc2["docs/installation.md"]:::docs
            Doc3["docs/contributing.md"]:::docs
            Doc4["docs/governance.md"]:::docs
        end
    end

    %% Layer 3: ROS Infrastructure
    subgraph "Layer 3: ROS Infrastructure" 
        direction TB
        RosBridge["ROS Bridge Node<br/>rosbridge_server"]:::infra
        RosCore["ROS1/ROS2 Core<br/>Topics, Services, Params"]:::infra
    end

    %% Layer 4: Robot Hardware/Simulator
    subgraph "Layer 4: Robot Hardware/Simulator"
        direction TB
        Hardware["Sensors & Actuators<br/>(Cameras, LIDAR, Motors,<br/>Isaac Sim)"]:::hardware
    end

    %% Connections
    LLM -->|"WebSocket (LLM JSON)"| Server
    Server -->|"JSON-RPC<br/>over WebSocket/TCP"| RosBridge
    RosBridge -->|"ROS API Calls"| RosCore
    RosCore -->|"Topic Messages, State"| Server
    Server -->|"Sensor Data JSON"| LLM

    %% Optional future flows
    Server -.->|"Action Support (future)"| RosCore
    LLM -.->|"Permission Controls (future)"| Server

    %% Click Events
    click Server "https://github.com/robotmcp/ros-mcp-server/blob/main/server.py"
    click WSManager "https://github.com/robotmcp/ros-mcp-server/blob/main/utils/websocket_manager.py"
    click NetUtils "https://github.com/robotmcp/ros-mcp-server/blob/main/utils/network_utils.py"
    click Config "https://github.com/robotmcp/ros-mcp-server/blob/main/pyproject.toml"
    click Ex1 "https://github.com/robotmcp/ros-mcp-server/tree/main/examples/1_turtlesim"
    click Ex2 "https://github.com/robotmcp/ros-mcp-server/tree/main/examples/2_gemini"
    click Ex3 "https://github.com/robotmcp/ros-mcp-server/tree/main/examples/3_limo_mobile_robot"
    click Ex4 "https://github.com/robotmcp/ros-mcp-server/tree/main/examples/4_unitree_go2"
    click Ex5 "https://github.com/robotmcp/ros-mcp-server/tree/main/examples/5_docker_turtlesim"
    click CI1 "https://github.com/robotmcp/ros-mcp-server/blob/main/.github/workflows/clone-trend.yml"
    click CI2 "https://github.com/robotmcp/ros-mcp-server/blob/main/.github/workflows/traffic-trend.yml"
    click Doc1 "https://github.com/robotmcp/ros-mcp-server/blob/main/README.md"
    click Doc2 "https://github.com/robotmcp/ros-mcp-server/blob/main/docs/installation.md"
    click Doc3 "https://github.com/robotmcp/ros-mcp-server/blob/main/docs/contributing.md"
    click Doc4 "https://github.com/robotmcp/ros-mcp-server/blob/main/docs/governance.md"

    %% Styles
    classDef external fill:#D0E1FF,stroke:#0366d6,color:#0366d6
    classDef middleware fill:#E6F4EA,stroke:#22863A,color:#22863A
    classDef infra fill:#FFF5E5,stroke:#D67C00,color:#D67C00
    classDef hardware fill:#F0F0F0,stroke:#6A737D,color:#6A737D
    classDef docs fill:#FFFFFF,stroke:#BBBBBB,color:#444444
```
