mcp-ros2-logs
Provides tools for analyzing ROS2 log files, including querying, summarizing, comparing runs, detecting anomalies, and correlating logs with ROS2 bag topics.
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., "@mcp-ros2-logs show me errors in the latest run"
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.
mcp-ros2-logs
An MCP server that gives AI agents the ability to analyze ROS2 log files across multiple nodes. It solves the core pain point of ROS2's fragmented logging — where each node writes to its own separate file — by merging them into a unified timeline and exposing smart query tools.
No ROS2 installation required. It just reads log files from disk.
Install
pipx install mcp-ros2-logsOr with pip (in a virtual environment):
pip install mcp-ros2-logsOr from source:
git clone https://github.com/spanchal001/mcp-ros2-logs.git
cd mcp-ros2-logs
pdm installRelated MCP server: ROS & LLM Integration Bridge
Setup
Claude Code
claude mcp add --scope user ros2-logs -- mcp-ros2-logsThis makes the server available in all Claude Code sessions. For project-scoped setup (current directory only), omit --scope user.
To set a custom log directory (and optionally a default result limit):
claude mcp add --scope user ros2-logs -e MCP_ROS2_LOGS_DIR=/path/to/logs -e MCP_ROS2_LOGS_MAX_RESULTS=50 -- mcp-ros2-logsClaude Desktop
Add to ~/.config/Claude/claude_desktop_config.json (Linux) or ~/Library/Application Support/Claude/claude_desktop_config.json (macOS):
{
"mcpServers": {
"ros2-logs": {
"command": "mcp-ros2-logs",
"env": {
"MCP_ROS2_LOGS_DIR": "/path/to/your/ros2/logs",
"MCP_ROS2_LOGS_MAX_RESULTS": "100"
}
}
}
}VS Code (GitHub Copilot)
Add to .vscode/mcp.json in your workspace:
{
"servers": {
"ros2-logs": {
"command": "mcp-ros2-logs",
"env": {
"MCP_ROS2_LOGS_DIR": "/path/to/your/ros2/logs",
"MCP_ROS2_LOGS_MAX_RESULTS": "100"
}
}
}
}Then use Copilot in agent mode (@workspace) to query your logs.
Cursor
Open Settings > MCP Servers > Add Server and configure:
{
"ros2-logs": {
"command": "mcp-ros2-logs",
"env": {
"MCP_ROS2_LOGS_DIR": "/path/to/your/ros2/logs",
"MCP_ROS2_LOGS_MAX_RESULTS": "100"
}
}
}Tools
list_runs
Discover available log runs in the log directory.
"list my ROS2 log runs"
"list runs in /tmp/robot_logs"load_run
Parse all log files in a run into a merged, sorted timeline.
"load the latest run"
"load bad_run from /tmp/robot_logs"query_logs
Search and filter the merged timeline. Supports severity, node, time range, text, and context window filters.
"show me all errors and fatals"
"find messages containing 'timeout' from sensor_driver"
"show errors with 5 messages of context around each match"
"show warnings in the last 30 seconds of the run"get_node_summary
Detailed analysis of a specific node: uptime, severity counts, recurring message patterns, unique errors, stack traces, and message rate.
"summarize the sensor_driver node"
"what errors did motion_planner have?"get_timeline
Condensed narrative of a run. Groups consecutive messages, highlights severity transitions (INFO -> ERROR), and flags gaps where nodes went silent.
"show me a timeline of the run"
"what's the timeline for the last 10 seconds?"compare_runs
Diff two runs to find what changed. Shows new/missing nodes, severity distribution changes, novel error messages, first divergence point, and timing differences.
"compare good_run vs bad_run"
"what's different between yesterday's run and today's?"detect_anomalies
Statistically flags unusual patterns using the first portion of a run as a baseline. Detects rate spikes, new error patterns, severity escalations, silence gaps, and error bursts.
"detect anomalies in bad_run"
"find anomalies with severity score above 0.5"list_bag_topics
List topics in a ROS2 bag file (.db3/.mcap) with message types and counts. No ROS2 installation or message deserialization needed.
"list bag topics in my_recording"query_bag_messages
Query bag messages filtered by topic and time range. Shows timestamps, topic names, message types, and sizes.
"show messages from /scan topic in my_recording"
"query bag messages from the last 10 seconds"correlate
Cross-reference log entries with bag topic messages within a time window. Shows what was happening on ROS2 topics around errors. Can correlate logs from one run with a bag from a different run.
"correlate errors in bad_run with bag from bag_recording"
"correlate errors with bag topics, 500ms window"tail_logs
Tail a log run for new entries since the last check. First call loads the run, subsequent calls return only new entries. Useful for monitoring an active ROS2 system.
"tail my_live_run"
"check for new log entries"MCP Resources
The server also exposes log data as browsable MCP resources:
URI | Description |
| List of available runs |
| Run overview (nodes, severity counts, time range) |
| Per-node detailed summary |
| Condensed narrative timeline |
| All ERROR/FATAL entries |
Log Path Resolution
The server resolves the log directory using this priority chain:
log_dirparameter on the tool callMCP_ROS2_LOGS_DIRenv varROS_LOG_DIRenv var$ROS_HOME/log/~/.ros/log/
It auto-detects whether a path is a single log file, a run directory (contains .log files), a bag directory (contains metadata.yaml), or a log root (contains run subdirectories).
Pagination
All list-returning tools support limit and offset parameters for paginating results. When results are truncated, the output includes a notice with the next offset value. The only exceptions are load_run and compare_runs, which return fixed-structure summaries.
The default limit is controlled by the MCP_ROS2_LOGS_MAX_RESULTS environment variable (default: 100). query_logs and query_bag_messages keep their own default of 50.
# Set a global default limit
claude mcp add --scope user ros2-logs -e MCP_ROS2_LOGS_MAX_RESULTS=50 -e MCP_ROS2_LOGS_DIR=/path/to/logs -- mcp-ros2-logsLog Format
Parses the standard ROS2 spdlog default format:
[SEVERITY] [EPOCH.NANOSECONDS] [node_name]: messageExample:
[INFO] [1713099970.190824925] [talker_node]: Publishing: Hello World 1
[WARN] [1713099975.443210100] [motion_planner]: Planning timeout after 500ms
[ERROR] [1713099975.501332000] [collision_checker]: No valid trajectory foundMulti-line messages (stack traces) are handled automatically.
Custom Log Formats
If your ROS2 nodes use a custom RCUTILS_CONSOLE_OUTPUT_FORMAT, pass it as an environment variable when registering the MCP server:
claude mcp add --scope user ros2-logs \
-e RCUTILS_CONSOLE_OUTPUT_FORMAT="{severity} {time} {name}: {message}" \
-- mcp-ros2-logsOr for Claude Desktop, add it to the env block:
{
"mcpServers": {
"ros2-logs": {
"command": "mcp-ros2-logs",
"env": {
"RCUTILS_CONSOLE_OUTPUT_FORMAT": "{severity} {time} {name}: {message}"
}
}
}
}Supported placeholders: {severity}, {time}, {name}, {message}, {function_name}, {file_name}, {line_number}.
When {name} is absent from the format, the node name is inferred from the log filename. When {time} is absent, entries are ordered by their position in the file.
Development
git clone https://github.com/spanchal001/mcp-ros2-logs.git
cd mcp-ros2-logs
pdm install
pdm run pytest
pdm run ruff check src/ tests/License
MIT
Available Tools
11 toolscompare_runs_toolA
Compare two ROS2 log runs to find what changed. Use after loading both runs.
Diffs a "good" run (run_id_1) against a "bad" run (run_id_2) to identify: new/missing nodes, severity distribution changes, novel error messages that only appear in run_2, the first divergence point, and timing differences for when errors first appeared.
Args: run_id_1: First run ID (typically the "good" or baseline run). run_id_2: Second run ID (typically the "bad" or failing run). log_dir: Optional path to log directory override.
Inputs: run_id_1 (required), run_id_2 (required), log_dir. Returns: result
correlate_toolA
Correlate log entries with bag topic messages within a time window.
Shows what was happening on ROS2 topics around the time of log events (typically errors). Can correlate logs from one run with a bag from a different run if they share the same time window.
Args: run_id: Run ID containing the log files. bag_run_id: Run ID containing the bag file. Defaults to run_id if not provided (same run has both logs and bag). severity: Log severity filter (default "ERROR,FATAL"). window_ms: Time window in milliseconds (default 100ms, symmetric). topics: Comma-separated topic names to include (default: all topics). limit: Maximum correlations to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of correlations to skip (default 0). log_dir: Optional path to log directory override.
Inputs: run_id (required), bag_run_id, severity, window_ms, +4 more. Returns: result
detect_anomalies_toolA
Detect anomalous patterns in a ROS2 log run. Use after load_run.
Statistically analyzes the run using the first portion as a baseline for "normal" behavior, then flags deviations: rate spikes, new error patterns, severity escalations, silence gaps, and error bursts.
Args: run_id: Run ID from list_runs or a direct path to a log file/directory. baseline_ratio: Fraction of the run (by time) to use as baseline (default 0.3 = first 30%). min_severity_score: Only return anomalies with severity_score >= this value (0.0-1.0). Default 0.0 returns all. limit: Maximum anomalies to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of anomalies to skip (default 0). log_dir: Optional path to log directory override.
Inputs: run_id (required), baseline_ratio, min_severity_score, limit, +2 more. Returns: result
get_node_summary_toolA
Get detailed analysis of a specific node's log activity. Use after load_run.
Provides a comprehensive summary of one node including uptime, message counts per severity, top recurring message patterns, all unique errors with timestamps, any stack traces found, and average message rate.
Args: run_id: Run ID from list_runs or a direct path to a log file/directory. node: Node name to analyze (e.g., "sensor_driver", "motion_planner"). limit: Cap unique_errors and stack_traces lists. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of items to skip in unique_errors and stack_traces (default 0). log_dir: Optional path to log directory override.
Inputs: run_id (required), node (required), limit, offset, +1 more. Returns: result
get_timeline_toolA
Get a condensed narrative summary of a ROS2 log run. Use after load_run.
Compresses the full log timeline into a readable narrative by grouping consecutive same-severity messages, highlighting severity transitions (e.g., INFO -> ERROR), and flagging gaps where a node went silent. Essential for quickly understanding what happened in a long run.
Args: run_id: Run ID from list_runs or a direct path to a log file/directory. time_start: Start time filter. ISO format, epoch, or relative ("-30s" = 30s before run end, "+10s" = 10s after run start). time_end: End time filter. Same format as time_start. nodes: Filter by node name(s). Comma-separated: "sensor_driver,planner". limit: Maximum events to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of events to skip (default 0). log_dir: Optional path to log directory override.
Inputs: run_id (required), time_start, time_end, nodes, +3 more. Returns: result
list_bag_topicsA
List topics in a ROS2 bag file with message types and counts.
Args: run_id: Bag directory name or path. limit: Maximum topics to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of topics to skip (default 0). log_dir: Optional path to log directory override.
Inputs: run_id (required), limit, offset, log_dir. Returns: result
list_runsA
List available ROS2 log runs with summary info.
Args: log_dir: Optional path to log directory. If not provided, resolves via MCP_ROS2_LOGS_DIR, ROS_LOG_DIR, or ~/.ros/log. limit: Maximum runs to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of runs to skip (default 0).
Inputs: log_dir, limit, offset. Returns: result
load_runC
Load and parse a ROS2 log run into a unified timeline.
Args: run_id: The run directory name or file path. log_dir: Optional path to log directory.
Inputs: run_id (required), log_dir. Returns: result
query_bag_messagesA
Query bag messages filtered by topic and time range.
Args: run_id: Bag directory name or path. topic: Filter by topic name (e.g., "/scan", "/cmd_vel"). time_start: Start time filter (epoch or relative "-30s"). time_end: End time filter (epoch or relative). limit: Maximum messages to return (default 50). offset: Number of messages to skip (default 0). log_dir: Optional path to log directory override.
Inputs: run_id (required), topic, time_start, time_end, +3 more. Returns: result
query_logs_toolA
Search and filter the merged ROS2 log timeline. Use after load_run.
Flexible query tool for finding specific log entries across all nodes. Supports filtering by severity, node, time range, and text content. The context parameter enables cross-node cascade analysis by including surrounding messages from ALL nodes around each match.
Args: run_id: Run ID from list_runs or a direct path to a log file/directory. severity: Filter by severity level(s). Comma-separated: "ERROR", "WARN,ERROR,FATAL". Case-insensitive. nodes: Filter by node name(s). Comma-separated: "sensor_driver", "planner,controller". time_start: Start time filter. ISO format ("2024-04-14T14:02:31"), epoch ("1713103351.0"), or relative ("-30s" = 30s before run end, "+10s" = 10s after run start). time_end: End time filter. Same format as time_start. text: Search message content. Plain substring by default. Interpreted as regex if it contains special characters (*, +, ?, [, etc). limit: Maximum entries to return (default 50). Total match count is always reported even if truncated. offset: Number of entries to skip (default 0). context: Include N messages before and after each match across ALL nodes. Enables cascade analysis (e.g., context=5 shows what happened on other nodes around each error). Overlapping context windows are merged. log_dir: Optional path to log directory override.
Inputs: run_id (required), severity, nodes, time_start, +6 more. Returns: result
tail_logs_toolA
Tail a ROS2 log run for new entries since last check.
First call loads the run and returns a summary. Subsequent calls return only new entries appended since the previous call. Useful for monitoring an active ROS2 system.
Args: run_id: Run ID from list_runs or a direct path to a log file/directory. limit: Maximum new entries to return. Defaults to MCP_ROS2_LOGS_MAX_RESULTS (100). offset: Number of new entries to skip (default 0). log_dir: Optional path to log directory override.
Inputs: run_id (required), limit, offset, log_dir. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 11 tools
Each tool has a distinct purpose: comparison, anomaly detection, timeline, querying, node analysis, bag operations, etc. Even similar tools like query_logs_tool and get_timeline_tool are clearly differentiated by their outputs (filtered entries vs condensed narrative). No two tools could be easily confused.
All tool names follow a consistent snake_case pattern, with most being verb_noun (list_runs, load_run) or verb_noun_tool (compare_runs_tool, correlate_tool). The '_tool' suffix is uniformly applied to analysis tools, and verbs are descriptive (query, tail, detect, compare). No mixing of conventions.
With 11 tools, the server covers all essential operations for ROS2 log analysis: loading, listing, querying, summarizing, comparing, anomaly detection, bag correlation, and monitoring. This is a well-scoped set that is neither too sparse nor overwhelming for the domain.
The tool surface covers the full lifecycle of log analysis: load, list, query, summarize, compare, detect anomalies, and even live tail. Minor gaps include no explicit tool to list all nodes in a run (though inferable from queries) and no export/visualization, but these do not hinder typical analysis workflows.
Maintenance
Related MCP Connectors
Ingest and search LogsLoom logs from coding agents.
Connect Claude, Cursor, Codex, and other AI tools to your robotics mission data.
Open-source agent that observes and fixes your application. Query logs, traces, metrics, incidents.
Structured knowledge base for AI agent solutions. Search, explore, and retrieve build logs.
Related MCP Servers
- 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
- AlicenseNot gradedqualityCmaintenanceEnables AI assistants to read and analyze Linux system logs—including systemd journal, syslog, kernel, application, and Docker container logs—for diagnostics and predictive analysis.MIT
- AlicenseAqualityBmaintenanceEnables LLM coding agents to inspect, control, and verify remote ROS2 robotics applications without a local ROS2 installation, supporting topics, services, actions, parameters, TF transforms, and automated test suites.16Apache 2.0