Skip to main content
Glama
mcp-ros2-logs

mcp-ros2-logs

by spanchal001

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-logs

Or with pip (in a virtual environment):

pip install mcp-ros2-logs

Or from source:

git clone https://github.com/spanchal001/mcp-ros2-logs.git
cd mcp-ros2-logs
pdm install

Related MCP server: ROS & LLM Integration Bridge

Setup

Claude Code

claude mcp add --scope user ros2-logs -- mcp-ros2-logs

This 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-logs

Claude 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

runs://list

List of available runs

runs://{run_id}/summary

Run overview (nodes, severity counts, time range)

runs://{run_id}/nodes/{node}/summary

Per-node detailed summary

runs://{run_id}/timeline

Condensed narrative timeline

runs://{run_id}/errors

All ERROR/FATAL entries

Log Path Resolution

The server resolves the log directory using this priority chain:

  1. log_dir parameter on the tool call

  2. MCP_ROS2_LOGS_DIR env var

  3. ROS_LOG_DIR env var

  4. $ROS_HOME/log/

  5. ~/.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-logs

Log Format

Parses the standard ROS2 spdlog default format:

[SEVERITY] [EPOCH.NANOSECONDS] [node_name]: message

Example:

[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 found

Multi-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-logs

Or 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 tools
compare_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

    A4/5.0

    Scored across 11 tools

    Disambiguation5/5

    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.

    Naming Consistency5/5

    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.

    Tool Count5/5

    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.

    Completeness4/5

    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

    ActivityInactive
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • 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
    • A
      license
      Not graded
      quality
      C
      maintenance
      Enables 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
    • A
      license
      A
      quality
      B
      maintenance
      Enables 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.
      16
      Apache 2.0