remote-ros-mcp
Provides tools for interacting with remote ROS2 robotics applications, enabling inspection and control of topics, services, actions, parameters, TF transforms, and automated verification suites.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@remote-ros-mcp measure the publish frequency of the /odom topic"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
rclpyor 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_goaldispatches 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-connectionandremote-ros-mcp inspect(--jsonsupported).
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) orpip
2. Installation
git clone <repo-url> remote-ros-mcp
cd remote-ros-mcp
uv sync3. 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.jsonmacOS:
~/Library/Application Support/remote-ros-mcp/config.jsonWindows:
%APPDATA%\remote-ros-mcp\config.jsonOverride 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 --json4. 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 |
| Verify wrosbridge connection and serving health |
| List active nodes, namespaces, pub/sub topics, and services | |
| List available topics with publisher/subscriber mapping | |
| List active services | |
| Read parameter values from a target node | |
| Update parameter values on a target node | |
| Lookup geometric coordinate transform between two frames | |
Data Exchange |
| Publish JSON payload to a ROS2 topic |
| Sample recent N messages or listen to live stream | |
| Call ROS2 service synchronously and receive JSON reply | |
| Send action goal, await completion, and summarize feedback | |
| Cancel active action goal | |
Testing & Verification |
| Assert message publication matching condition expression |
| Measure topic publishing rate (Hz), period, and jitter | |
| Inject simulated message sequence to verify subscriber behavior | |
| 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 toolsros2_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
Scored across 16 tools
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.
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.
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.
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
Related MCP Connectors
Operate Linux, macOS and Windows from your LLM. Every action runs through an auditable allowlist.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
AI Agent Utility Layer for agent safety, web monitoring, crypto research and tool discovery.
Memory, reflection and safety for AI agents. Hosted or local, no vector database.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseNot gradedqualityDmaintenanceEnables 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
- AlicenseAqualityBmaintenanceConnects AI agents like Claude to live ROS2 robots, enabling natural language interaction for diagnostics, parameter tuning, and control with safety sandboxing.161MIT