Provides tools for analyzing ROS2 log files, including querying, summarizing, comparing runs, detecting anomalies, and correlating logs with ROS2 bag topics.
Click on "Install 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.
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.
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 MCP
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-logsAdd 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"
}
}
}
}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.
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"
}
}
}Discover available log runs in the log directory.
"list my ROS2 log runs"
"list runs in /tmp/robot_logs"Parse all log files in a run into a merged, sorted timeline.
"load the latest run"
"load bad_run from /tmp/robot_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"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?"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?"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?"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 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 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"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 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"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 |
The server resolves the log directory using this priority chain:
log_dir parameter on the tool call
MCP_ROS2_LOGS_DIR env var
ROS_LOG_DIR env 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).
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-logsParses 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.
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.
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/MIT
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id_1 | Yes | ||
| run_id_2 | Yes | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full burden. It implies the tool is read-only (comparing runs) but does not explicitly state it has no side effects, permissions needed, or error behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is front-loaded with a brief purpose statement, followed by a bullet-point list of specific comparisons. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity and the presence of an output schema, the description adequately covers the comparison behavior. It could be more explicit about return value structure, but the output schema reduces that burden.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, but the description provides detailed semantics for all three parameters: run_id_1 as the 'good' baseline, run_id_2 as the 'bad' run, and log_dir as an optional override. This adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'compare' and the resource 'ROS2 log runs', and lists specific outputs like new/missing nodes and severity changes. It distinguishes from siblings by focusing on pairwise comparison.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description includes a prerequisite ('Use after loading both runs'), which provides clear usage context. However, it does not explicitly exclude alternatives or mention when not to use this tool.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| bag_run_id | No | ||
| severity | No | ERROR,FATAL | |
| window_ms | No | ||
| topics | No | ||
| limit | No | ||
| offset | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It explains the correlation operation and mentions a symmetric time window, but does not disclose whether the tool is read-only, performance implications, error handling, or side effects. This is adequate but not highly transparent.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a summary sentence, a practical use sentence, and a clear parameter list. It is appropriately sized for 8 parameters, though it could be slightly more concise without losing clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given that an output schema exists (context signal indicates true), the description does not need to explain return values. It covers the core functionality and parameter details, but lacks discussion of prerequisites or error cases. For a tool with no annotations, it is fairly complete.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description fully compensates. It provides semantic detail for all 8 parameters, including defaults and explanations (e.g., severity filter, default window of 100ms, bag_run_id falls back to run_id). This adds substantial value beyond the input schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the verb 'correlate' with a specific resource ('log entries with bag topic messages') and a time window. It distinguishes this from sibling tools like query_logs_tool and query_bag_messages by combining both data sources.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explicitly states the use case: showing topic messages around log events, typically errors. It also explains cross-run correlation capability. However, it does not explicitly mention when not to use or alternatives, though the purpose makes it clear.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| baseline_ratio | No | ||
| min_severity_score | No | ||
| limit | No | ||
| offset | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description fully explains the behavior: it statistically analyzes using the first portion as baseline, flags deviations like rate spikes and error bursts. This is transparent about the method. It does not mention any side effects, but the tool is likely read-only, so no contradiction.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a brief intro paragraph and a bullet-like Args list. Every sentence adds value; no fluff. It is concise while being informative, fitting within a few lines.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool complexity (6 parameters, no annotations), the description covers all necessary context: purpose, usage step (after load_run), algorithm (baseline approach), parameter details, and types of anomalies. The presence of an output schema means return values need not be described, so completeness is excellent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite 0% schema coverage, the description provides thorough explanations for all 6 parameters in the Args section, including defaults, constraints (e.g., 0.0-1.0 for min_severity_score), and purpose. This adds essential meaning beyond the schema's type and default.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Detect anomalous patterns in a ROS2 log run.' It specifies the verb (detect), resource (anomalies in log run), and distinguishes from siblings like compare_runs or query_logs by focusing on anomaly detection using a baseline.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear usage guideline: 'Use after load_run.' It implicitly tells when to use (post-load) and lists specific anomaly types, which helps differentiate. However, it does not explicitly state when not to use or provide alternatives, which prevents a 5.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| node | Yes | ||
| limit | No | ||
| offset | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations provided, so description carries full burden. Lists output contents comprehensively (uptime, message counts, patterns, errors, stack traces, rate). Describes limit/offset parameter behavior. No side effects or destructive actions; appropriate for read-only analysis.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured: purpose sentence with usage note, bulleted output summary, then labeled Arg definitions. Front-loaded key action. Every sentence adds value; no verbose or redundant content.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given 5 parameters, no annotations, and output schema not shown, description thoroughly covers purpose, usage, all parameters, and expected output content. Complete enough for agent to select and invoke correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but description provides full parameter explanations: run_id source options, node example, limit default (MCP_ROS2_LOGS_MAX_RESULTS), offset default, optional log_dir. Adds significant meaning beyond schema types.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
Clearly states specific verb ('Get detailed analysis') and resource ('node's log activity'). Distinguishes from siblings by specifying 'Use after load_run' and focusing on single node summary.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly advises 'Use after load_run', indicating prerequisite. No explicit when-not-to-use or alternatives, but context makes it clear this is for single-node deep dive.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| time_start | No | ||
| time_end | No | ||
| nodes | No | ||
| limit | No | ||
| offset | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations exist, so the description carries full burden. It discloses that the tool compresses logs, highlights severity transitions, and flags silent gaps, which goes beyond a basic 'get summary' and reveals behavioral traits. Does not contradict annotations.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear first sentence stating purpose, a usage note, a brief paragraph explaining behavior, and then Args. It is slightly verbose but still efficient and front-loaded; every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (7 parameters, 0% schema coverage), the description thoroughly documents all parameters and explains the output nature (condensed narrative, transitions, gaps). The presence of an output schema covers return values, so the description is complete for invoking this tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, but the description provides extensive parameter documentation in Args, explaining run_id, time_start/time_end formats (ISO, epoch, relative), nodes as comma-separated, limit default, offset, and log_dir. This adds significant meaning beyond the schema's bare types and titles.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states it gets a 'condensed narrative summary of a ROS2 log run' and explains its function: compressing consecutive same-severity messages, highlighting severity transitions, and flagging silent gaps. This distinguishes it from sibling tools like query_logs_tool or tail_logs_tool which provide detailed logs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
Explicitly says 'Use after load_run', giving clear context for when to invoke. Does not explicitly state when not to use or list alternatives, but the purpose as a high-level summary implies it should be used for quick overviews rather than detailed analysis.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| limit | No | ||
| offset | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations, the description only implies a read operation, but lacks details on side effects, permissions, or constraints beyond parameter defaults.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is very concise: a clear first sentence defining purpose, followed by a compact argument list with no superfluous text.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
While parameter descriptions are present and an output schema exists, the description lacks examples, error handling info, and more precise guidance on run_id format, making it adequate but not comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Given 0% schema coverage, the description provides meaningful explanations for each parameter, including default values for limit and offset, and clarifies run_id as directory name/path.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool lists topics in a ROS2 bag file with message types and counts, which distinguishes it from siblings like list_runs and query_bag_messages.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance on when to use this tool versus alternatives; it only describes parameters without contextual usage or exclusions.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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).
| Name | Required | Description | Default |
|---|---|---|---|
| log_dir | No | ||
| limit | No | ||
| offset | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries full behavioral disclosure. It describes resolution and defaults but does not cover error handling (e.g., missing directory) or performance implications. Adequate but not exhaustive.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured in a Google-style docstring, front-loading the purpose. It is clear but slightly verbose given the parameter details could be more terse; still efficient overall.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
The description covers key behaviors for a list tool: resolution, limits, offset. An output schema exists, so return values are not needed. It does not discuss pagination or empty results, but this is acceptable for a straightforward listing function.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description compensates by explaining each parameter's purpose and default resolution logic (e.g., log_dir resolves via env vars, limit defaults to MCP_ROS2_LOGS_MAX_RESULTS). This adds meaning beyond the schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'List available ROS2 log runs with summary info,' providing a specific verb and resource. It distinguishes from sibling tools like get_node_summary_tool and list_bag_topics by focusing on listing runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the resolution logic for log_dir when not provided, including environment variables and defaults. It also specifies default values for limit and offset. However, it does not explicitly state when to use this tool over alternatives.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description bears full responsibility for disclosing behavior. It only states 'load and parse' without indicating side effects (e.g., caching, mutation), resource requirements, or operational constraints. For a load operation, this is insufficient.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise, with a clear purpose statement followed by parameter explanations. However, the parameter info partially duplicates the schema. It is well-structured but could be front-loaded more aggressively.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown) and the tool's relatively simple interface (2 params, no annotations), the description is adequate but minimal. It does not address common use cases or edge cases (e.g., path resolution, error handling).
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds brief explanations for both parameters: 'run_id' is 'The run directory name or file path' and 'log_dir' is 'Optional path to log directory'. While the schema has no descriptions (0% coverage), these sentences provide some meaning beyond raw field names, but are minimal.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description uses a specific verb-resource pair ('load and parse a ROS2 log run') and states the outcome ('unified timeline'). It is clear and distinct from sibling tools like 'list_runs' or 'query_logs_tool', but does not explicitly differentiate itself.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
No guidance is given on when to use this tool versus alternatives. The description does not mention prerequisites, such as whether a run must first be listed with 'list_runs', or when to prefer other tools like 'get_timeline_tool' or 'query_bag_messages'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| topic | No | ||
| time_start | No | ||
| time_end | No | ||
| limit | No | ||
| offset | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden. It discloses filtering behavior and pagination (limit, offset) but does not explicitly state that the operation is read-only or non-destructive. It also does not mention error handling for missing run_id or performance implications, which is a minor gap.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is concise: a single sentence overview followed by a well-organized Args list. Every line adds value, and the critical information is front-loaded. There is no unnecessary repetition or fluff.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the presence of an output schema (not shown), the description is not required to detail return values. It covers all 7 parameters adequately. However, it omits potential edge cases like empty results or error handling for invalid run_id, which slightly reduces completeness for an agent.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Despite schema description coverage being 0%, the description adds substantial meaning to each parameter. It provides examples (e.g., '/scan' for topic, '-30s' for time_start) and clarifies defaults (limit=50, offset=0) and roles (run_id as bag directory). This goes well beyond the schema's type-only definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states 'Query bag messages filtered by topic and time range,' which is a specific verb (query) and resource (bag messages). It distinguishes from sibling tools like list_bag_topics, which lists topics rather than messages. The filtering criteria are explicitly mentioned, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies the tool is for querying filtered bag messages, but it does not provide explicit guidance on when to use it versus alternatives. No exclusions or comparisons to siblings (e.g., list_bag_topics for topic discovery) are included. Usage context is implied but not formally stated.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| severity | No | ||
| nodes | No | ||
| time_start | No | ||
| time_end | No | ||
| text | No | ||
| limit | No | ||
| offset | No | ||
| context | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description fully details behavioral aspects: it explains filtering, the context parameter for cross-node analysis, pagination via limit/offset, and that total match count is always reported. It implicitly indicates a read-only operation, and no contradictions are present.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured: a concise one-line purpose, a brief overview paragraph, and a well-organized Args section. Every sentence adds value, and the bullet-like format enhances readability without unnecessary verbosity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity of the tool (10 parameters, including time and context handling), the description covers all essential aspects: prerequisites, each parameter's meaning and format, behavior of context merging, and pagination details. An output schema exists (though not shown), so return values are not required. The description is fully adequate for an agent to use the tool correctly.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The input schema has 0% description coverage, so the description carries the full burden. It provides detailed explanations for all 10 parameters, including format examples for time fields, behavior of text (substring vs regex), and context merging. This adds significant meaning beyond the schema's type definitions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Search and filter the merged ROS2 log timeline.' It specifies a specific verb ('search and filter') and a distinct resource ('merged ROS2 log timeline'), and mentions a prerequisite ('Use after load_run'), which helps differentiate it from sibling tools like tail_logs_tool or list_runs.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description gives a clear prerequisite ('Use after load_run') and implies usage context for filtering specific entries. However, it does not explicitly state when not to use this tool or directly compare it to alternatives like tail_logs_tool or query_bag_messages, which would further guide selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
| Name | Required | Description | Default |
|---|---|---|---|
| run_id | Yes | ||
| limit | No | ||
| offset | No | ||
| log_dir | No |
| Name | Required | Description |
|---|---|---|
| result | Yes |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
Since no annotations are provided, the description carries the full burden. It discloses the stateful behavior (first call vs subsequent calls), the purpose of parameters, and the general monitoring use case. It does not detail error handling or the exact return format, but that is covered by the output schema.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is functional and clear but slightly verbose due to the docstring-style parameter list. It could be more concise while retaining clarity, but it is not overly long.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool is a simple tail operation with an output schema (not shown), the description covers the essential behavior and parameters. It does not explicitly mention the stateful nature in a prominent way or how it differs from 'query_logs_tool' for log retrieval, but overall it is sufficient.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema coverage is 0%, so the description must explain parameters. It does so thoroughly: run_id can be from list_runs or a direct path, limit defaults to MCP_ROS2_LOGS_MAX_RESULTS (100), offset defaults to 0, and log_dir is an optional override. This adds significant meaning beyond the raw schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool 'tails a ROS2 log run for new entries since last check', which is a specific verb and resource. It distinguishes itself from sibling tools like 'list_runs' (listing runs) and 'query_logs_tool' (querying logs).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description explains the stateful behavior (first call returns summary, subsequent calls return new entries) and mentions it is 'useful for monitoring an active ROS2 system'. However, it does not explicitly state when not to use this tool or compare it to alternatives like 'query_logs_tool'.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
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.
Persistent memory and knowledge management for AI agents with semantic search and 50+ tools.
Build, validate, and deploy multi-agent AI solutions from any AI environment.
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/spanchal001/mcp-ros2-logs'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
