MCP ROS Bags
A Model Context Protocol (MCP) server for analyzing and querying ROS bag files. This server enables Claude and other MCP-compatible tools to interact with robot data stored in ROS bags.
Overview
This MCP server provides comprehensive tools for ROS bag analysis, supporting both ROS 1 and ROS 2 bag formats (.bag, .db3, .mcap). It enables AI assistants to query robot trajectories, sensor data, transforms, and logging information from recorded robot sessions.
Key Features
- Bag Management: List, inspect, and query ROS bag files
- Message Querying: Get messages by topic, timestamp, or time range
- Trajectory Analysis: Extract robot paths, waypoints, and motion profiles
- Sensor Data: Analyze laserscan topics, images
- Transform Trees: Query coordinate transforms and frame relationships
- Logging Analysis: Search and analyze ROS log messages
- Visualization: Generate plots and visual representations of data
- Search & Discovery: Find objects, patterns, and correlations in data
Installation
-
Clone the repository:
git clone https://github.com/binabik-ai/mcp-rosbags.git cd mcp-rosbags
-
Create and activate a Python virtual environment:
python3 -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate
-
Install dependencies:
pip install -r requirements.txt
-
Optional: Install with ROS 2 support:
pip install -e .[ros2]
Configuration
Claude Desktop Configuration
Add this to your Claude Desktop configuration file:
{
"mcpServers": {
"rosbag_reader": {
"command": "/path/to/your/venv/bin/python",
"args": ["/path/to/mcp-rosbags/src/server.py"],
"env": {
"PYTHONPATH": "/path/to/mcp-rosbags/src",
"MCP_ROSBAG_DIR": "/path/to/your/rosbags",
"MCP_ROSBAG_CONFIG": "/path/to/mcp-rosbags/src/config"
}
}
}
}
Environment Variables
MCP_ROSBAG_DIR: Default directory containing ROS bag files (default:./rosbags)MCP_ROSBAG_CONFIG: Configuration directory (default:./config)
Server Configuration
The server uses configuration files in the src/config/ directory:
server_config.yaml: Main server configuration (caching, timeouts, etc.)message_schemas.yaml: Schema definitions for message field extraction
Usage
With Claude Desktop
After configuration, restart Claude Desktop and you can interact with your ROS bags:
"List all ROS bags in my directory"
"Show me the trajectory from the /odom topic"
"Find all error messages in the logs"
"Extract an image from the /camera/image topic at timestamp 1234567890 and describe what you see"
Tools Overview
The server provides the following categories of tools:
Core Tools
set_bag_path: Set current bag file or directorylist_bags: List available ROS bag filesbag_info: Get detailed bag informationget_message_at_time: Get message at specific timestampget_messages_in_range: Get messages within time range
Analysis Tools
- Trajectory: Extract robot paths, analyze motion patterns
- LiDAR: Process laserscan data, e.g., to detect obstacles
- Images: Extract and process camera images
- Transforms: Query coordinate transforms and frame trees
- Logging: Search and analyze ROS log messages
- Visualization: Generate plots and visual data representations
Search Tools
- Pattern matching in message data
- Correlation analysis between topics
- Time-based data alignment
Architecture
src/
├── server.py # Main MCP server
├── config/ # Configuration files
│ ├── server_config.yaml # Server settings
│ └── message_schemas.yaml # Message field schemas
├── core/ # Core utilities
│ ├── cache_manager.py # Caching system
│ ├── message_utils.py # Message processing
│ └── schema_manager.py # Schema handling
└── extractors/ # Specialized analysis tools
├── bag_management.py # Bag operations
├── image.py # Image processing
├── lidar.py # LiDAR analysis
├── logging.py # Log analysis
├── search.py # Search and correlation
├── tf_tree.py # Transform trees
├── trajectory.py # Path analysis
└── visualization.py # Data visualization
Supported Message Types
The server supports standard ROS message types including:
- Navigation:
nav_msgs/Odometry,nav_msgs/Path - Geometry:
geometry_msgs/PoseStamped,geometry_msgs/Twist - Sensors:
sensor_msgs/LaserScan,sensor_msgs/PointCloud2,sensor_msgs/Image - Transforms:
tf2_msgs/TFMessage,geometry_msgs/TransformStamped - Diagnostics:
diagnostic_msgs/DiagnosticArray - Logging:
rcl_interfaces/Log
Performance Features
- Intelligent Caching: Configurable caching system for frequently accessed data
- Schema-based Extraction: Efficient field extraction using predefined schemas
License
This project is licensed under the Apache License 2.0. See LICENSE for details.
Support
- Issues: Report bugs and request features on GitHub Issues
- Contact: dev@binabik.ai
Acknowledgments
Built with the Model Context Protocol and the rosbags library.
Metadata
Release files for iflow-mcp_binabik-ai-mcp-rosbag-server 0.1.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1.tar.gz | 38.9 kB | Without provenance | Details for iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1-py3-none-any.whl |
Total release size: 87.3 kB
Release files / iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1.tar.gz
| Download URL | iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1.tar.gz |
|---|---|
| Size | 38.9 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
c85ad92eabf644518bbc5cd50f67522e09c5fa0950f01b14b34c3ef9dd3aa370
|
|
BLAKE2b-256 checksum How to use checksums |
42c0356f2e02bc21aa94f743ddbb5286f2183ff8dec31b14525239f2f68ffea7
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1-py3-none-any.whl
| Download URL | iflow_mcp_binabik_ai_mcp_rosbag_server-0.1.1-py3-none-any.whl |
|---|---|
| Size | 48.4 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
856fdc2fcb010f9fa16394576902c69a610d35b177913866107f6032036c4005
|
|
BLAKE2b-256 checksum How to use checksums |
5c706722fbd97effae4362b33788d503da099eb4898f90c3166f280aaa78bb73
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.10.0 {"installer":{"name":"uv","version":"0.10.0","subcommand":["publish"]},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"Debian GNU/Linux","version":"13","id":"trixie","libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_binabik-ai-mcp-rosbag-server 0.1.1
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.