Skip to main content
Glama

remote-ros-mcp

한국어 안내 (README_KO.md) | Developer Guidelines (AGENTS.md) | Changelog

remote-ros-mcp is a production-grade Model Context Protocol (MCP) server that empowers LLM coding agents (Claude Desktop, Cursor, Antigravity, etc.) to interact with, control, and verify remote ROS2 robotics applications.

Built to pair with the high-performance C++17/ROS2 Jazzy API Gateway wrosbridge, it allows LLM agents to inspect topics, services, actions, parameters, TF transforms, and execute real-time automated verification suites without requiring any local ROS2 installation.


🌟 Highlights

  • Zero Local ROS2 Dependency: Operates entirely over standard TCP/gRPC. No rclpy or ROS2 environment is required on the host or agent machine.

  • Bi-directional CDR <-> JSON Codec Engine: Translates Little-Endian ROS2 CDR byte streams into clean, validated Python dictionaries/JSON for LLMs.

  • Testing & Verification Suite:

    • ros2_assert_topic_published: Assert message arrival matching Python expressions (e.g. msg['linear']['x'] > 0.5).

    • ros2_measure_topic_hz: Real-time topic frequency, period, and jitter analysis.

    • ros2_mock_publish_sequence: Sequence injector to stimulate and test subscriber nodes.

    • ros2_record_and_inspect: Topic data recording and statistical summary.

  • One-stop ROS2 Action Support: ros2_action_send_goal dispatches goals, monitors progress, and waits for final results.

  • Enterprise Security: Full TLS encryption and API key header (x-api-key) authentication.

  • Standalone CLI: Diagnoses remote nodes and topics directly via remote-ros-mcp test-connection and remote-ros-mcp inspect (--json supported).


Related MCP server: ROS2 MCP Server

🛠 Architecture

[LLM Coding Agent (Cursor / Claude / Antigravity)]
                    │
                    │ MCP Protocol (JSON-RPC over stdio)
                    ▼
          ┌─────────────────────┐
          │   remote-ros-mcp    │
          │   (FastMCP Server)  │
          │ ┌─────────────────┐ │
          │ │ CDR <-> JSON    │ │
          │ │ Codec Engine    │ │
          │ └─────────────────┘ │
          └──────────┬──────────┘
                     │
                     │ gRPC + TLS / API-Key
                     ▼
          ┌─────────────────────┐
          │     wrosbridge      │
          │ (ROS2 Jazzy Gateway)│
          └──────────┬──────────┘
                     │
                     │ rclcpp (CDR)
                     ▼
          [ROS2 Robot Node Graph]

🚀 Quick Start

1. Requirements

  • Python 3.11+

  • uv (recommended) or pip

2. Installation

git clone <repo-url> remote-ros-mcp
cd remote-ros-mcp
uv sync

3. Configuration Management

remote-ros-mcp adheres to OS-standard configuration paths (XDG on Linux, Application Support on macOS, AppData on Windows) with layered precedence: CLI flags > Environment Variables > config.json > Defaults.

  • Default Config Path:

    • Linux: ~/.config/remote-ros-mcp/config.json

    • macOS: ~/Library/Application Support/remote-ros-mcp/config.json

    • Windows: %APPDATA%\remote-ros-mcp\config.json

    • Override Variable: REMOTE_ROS_CONFIG_PATH

# Print config path (using rrmcp alias)
uv run rrmcp config path

# Initialize default configuration
uv run rrmcp config init

# Set configuration parameters
uv run rrmcp config set host 192.168.1.100
uv run rrmcp config set port 50051

# View active configuration
uv run rrmcp config show --json

4. CLI Diagnostics

# Test connection health
uv run rrmcp test-connection

# Machine-readable JSON output
uv run rrmcp test-connection --json

# Discover active ROS2 graph
uv run rrmcp inspect --json

🤖 LLM Agent Integration

Claude Desktop (claude_desktop_config.json)

{
  "mcpServers": {
    "remote-ros": {
      "command": "uv",
      "args": [
        "--directory",
        "/absolute/path/to/remote-ros-mcp",
        "run",
        "remote-ros-mcp",
        "run"
      ],
      "env": {
        "ROS_BRIDGE_HOST": "127.0.0.1",
        "ROS_BRIDGE_PORT": "50051"
      }
    }
  }
}

📋 MCP Tools Reference

Category

Tool

Description

Graph & Introspection

ros2_health_check

Verify wrosbridge connection and serving health

ros2_get_nodes

List active nodes, namespaces, pub/sub topics, and services

ros2_get_topics

List available topics with publisher/subscriber mapping

ros2_get_services

List active services

ros2_get_parameters

Read parameter values from a target node

ros2_set_parameters

Update parameter values on a target node

ros2_lookup_tf

Lookup geometric coordinate transform between two frames

Data Exchange

ros2_topic_publish

Publish JSON payload to a ROS2 topic

ros2_topic_echo

Sample recent N messages or listen to live stream

ros2_call_service

Call ROS2 service synchronously and receive JSON reply

ros2_action_send_goal

Send action goal, await completion, and summarize feedback

ros2_action_cancel_goal

Cancel active action goal

Testing & Verification

ros2_assert_topic_published

Assert message publication matching condition expression

ros2_measure_topic_hz

Measure topic publishing rate (Hz), period, and jitter

ros2_mock_publish_sequence

Inject simulated message sequence to verify subscriber behavior

ros2_record_and_inspect

Record topic data for N seconds and return statistical summary


🧪 Testing & Quality

Strict compliance with the ncli view 24 engineering checklist:

# Run 24 unit & integration tests against in-memory mock server
uv run pytest -v

# Run with test coverage
uv run pytest --cov=remote_ros_mcp --cov-report=term-missing

# Lint & code format checks
uv run ruff check .
uv run ruff format --check .

📄 License

Apache License 2.0. See LICENSE for details.

Available Tools

16 tools
ros2_action_cancel_goalB

Cancel an executing ROS2 action goal.

    Args:
        action_name: Name of the action
        goal_id: Identifier of the goal to cancel
    

Inputs: goal_id (required), action_name (required). Returns: result

ros2_action_send_goalA

Send a goal to a ROS2 Action server and optionally wait for result.

    Args:
        action_name: Name of the action (e.g. '/navigate_to_pose')
        action_type: Action type identifier (e.g. 'nav2_msgs/action/NavigateToPose')
        goal_data: Goal definition as JSON dict
        wait_for_result: Whether to block until goal completes or times out
        timeout_sec: Maximum timeout to wait for result
    

Inputs: goal_data (required), action_name (required), action_type (required), timeout_sec, +1 more. Returns: result

ros2_assert_topic_publishedA

Assert that a message matching an optional condition has been published to a topic.

    Args:
        topic: Topic to check (e.g. '/robot/cmd_vel')
        topic_type: Message type string (e.g. 'geometry_msgs/msg/Twist')
        condition_expr: Python expression evaluating 'msg' (e.g. "msg['linear']['x'] > 0.5")
        timeout_sec: Max wait duration in seconds
    

Inputs: topic (required), topic_type (required), timeout_sec, condition_expr. Returns: result

ros2_call_serviceA

Call a ROS2 service and receive the response.

    Args:
        service: Service name (e.g. '/add_two_ints' or '/robot/reset_odometry')
        service_type: Service type (e.g. 'example_interfaces/srv/AddTwoInts')
        request_data: Request parameters as JSON object/dict
        timeout_sec: Maximum wait time for service response
    

Inputs: service (required), request_data (required), service_type (required), timeout_sec. Returns: result

ros2_get_nodesA

List all active ROS2 nodes with namespace, pub/sub topics, and services.

Inputs: no named parameters. Returns: result

ros2_get_parametersB

Get parameter values for a specific ROS2 node.

    Args:
        node_name: Full name of the node (e.g. '/robot/diff_drive_controller')
        names: List of parameter names to read
    

Inputs: names (required), node_name (required). Returns: result

ros2_get_servicesA

List all active ROS2 services available in the graph.

Inputs: no named parameters. Returns: result

ros2_get_topicsA

List all available ROS2 topics along with their publisher and subscriber nodes.

Inputs: no named parameters. Returns: result

ros2_health_checkA

Check the connection and serving health of the remote wrosbridge gateway.

Inputs: no named parameters. Returns: result

ros2_lookup_tfA

Lookup geometric coordinate transform between two frames from ROS2 TF tree.

    Args:
        target_frame: Target coordinate frame (e.g. 'odom' or 'map')
        source_frame: Source coordinate frame (e.g. 'base_link' or 'camera_link')
        timeout_sec: Timeout in seconds
    

Inputs: source_frame (required), target_frame (required), timeout_sec. Returns: result

ros2_measure_topic_hzA

Measure publishing frequency (Hz) and period statistics of a topic.

    Args:
        topic: ROS2 topic to measure
        topic_type: Type of message
        sample_count: Target number of samples to record
        timeout_sec: Maximum collection time
    

Inputs: topic (required), topic_type (required), timeout_sec, sample_count. Returns: result

ros2_mock_publish_sequenceB

Publish a sequence of mock messages to stimulate and test subscriber nodes.

    Args:
        topic: Target topic name
        topic_type: Message type identifier
        sequence: List of JSON message objects to publish in order
        interval_sec: Delay between each published message
    

Inputs: topic (required), sequence (required), topic_type (required), interval_sec. Returns: result

ros2_record_and_inspectC

Record topic messages for a period and return summary statistics.

    Args:
        topic: Topic to record
        topic_type: Message type
        duration_sec: Recording duration in seconds
    

Inputs: topic (required), topic_type (required), duration_sec. Returns: result

ros2_set_parametersC

Set runtime parameters for a specific ROS2 node.

    Args:
        node_name: Full name of the node (e.g. '/robot/diff_drive_controller')
        parameters: Key-value dictionary of parameters to update
    

Inputs: node_name (required), parameters (required). Returns: result

ros2_topic_echoB

Capture and return messages from a ROS2 topic.

    Args:
        topic: Topic name to listen to (e.g. '/robot/cmd_vel')
        topic_type: Message type (e.g. 'geometry_msgs/msg/Twist')
        count: Number of messages to capture (default 1)
        timeout_sec: Maximum time to wait in seconds
    

Inputs: topic (required), topic_type (required), count, timeout_sec. Returns: result

ros2_topic_publishB

Publish a message to a ROS2 topic.

    Args:
        topic: ROS2 topic name (e.g. '/robot/cmd_vel')
        topic_type: Message type string (e.g. 'geometry_msgs/msg/Twist')
        data: Message content as JSON object/dict
    

Inputs: data (required), topic (required), topic_type (required). Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.5/5.0

    Scored across 16 tools

    Disambiguation4/5

    Most tools target distinct ROS2 resources and operations—topics, services, actions, parameters, TF, and graph introspection are clearly separated. Minor overlap exists between ros2_topic_publish and ros2_mock_publish_sequence, and between ros2_record_and_inspect and ros2_measure_topic_hz, but descriptions clarify their different intents.

    Naming Consistency3/5

    All tool names share a ros2_ prefix and use lowercase snake_case, making them readable and recognizable. However, the internal structure is inconsistent: some are verb-first like ros2_get_nodes and ros2_set_parameters, while others are resource-first like ros2_topic_publish and ros2_action_send_goal, and a few like ros2_record_and_inspect or ros2_health_check break the pattern entirely.

    Tool Count4/5

    Sixteen tools is slightly above the typical well-scoped range, but each tool covers a distinguishable ROS2 interaction or inspection capability. The extra testing-oriented tools like assert, measure, and mock-publish add value without feeling redundant.

    Completeness4/5

    The server covers the major ROS2 interaction surfaces: graph introspection, topics, services, actions, parameters, TF, and health checking. Notable gaps include no way to list message/service/action type definitions and no action goal status listing, but these are workable limitations rather than fatal omissions.

    Maintenance

    ActivitySlowing
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables control of ROS/ROS2 robots through natural language commands by translating LLM instructions into ROS topics and services. Supports cross-platform WebSocket-based communication with existing robot systems without requiring code modifications.
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI tools to interact with ROS2 robotics systems through natural language commands. Supports topic publishing/subscribing, service calls, message analysis, and auto-discovery of ROS2 interfaces for debugging and controlling robots.
      Mozilla Public 2.0
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables large language models to interact with ROS robots seamlessly, allowing natural language control, real-time sensor monitoring, and autonomous task execution without modifying existing robot code.
      Apache 2.0