mdfmcp

MDF MCP Server

A Model Context Protocol (MCP) server for analyzing ASAM MDF (Measurement Data Format) files. Enables AI assistants to access and analyze automotive and industrial measurement data.

🚀 Quick Start

Using uvx (Recommended)

# Install uv (if not already installed)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Run the server directly
uvx mcp-server-mdf

Local Development

# Clone and setup
git clone https://github.com/Shanko-26/mdfmcp
cd mdfmcp

# Install in virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate
pip install -e .

# Run the server
mcp-server-mdf

📋 Features

• MDF File Support: Versions 2.x, 3.x, and 4.x
• AI-Native Interface: Designed for LLM integration
• Data Analysis: Statistics, plotting, signal processing
• Format Export: CSV, HDF5, Parquet, MATLAB
• Session Management: Multi-file support
• High Performance: Efficient large file handling

🔧 Configuration

Important: This MCP server requires direct file system access to read MDF files. It works best with IDEs that support local file operations.

Compatible IDEs

For VS Code with Continue.dev

Add to your MCP configuration:

{
  "mcpServers": {
    "mdf": {
      "command": "uvx",
      "args": ["mcp-server-mdf@latest"]
    }
  }
}

For Cursor IDE

Add to ~/.cursor/mcp.json:

{
  "mcpServers": {
    "mdf": {
      "command": "uvx",
      "args": ["mcp-server-mdf@latest"]
    }
  }
}

For Windsurf/Codeium

Follow your IDE's MCP configuration guide with the same uvx command.

Troubleshooting uvx Path Issues

If you get "command not found" errors, find your uvx path:

which uvx  # On macOS/Linux  
where uvx  # On Windows

Then use the full path in your configuration:

{
  "mcpServers": {
    "mdf": {
      "command": "/Users/username/.local/bin/uvx",
      "args": ["mcp-server-mdf"]
    }
  }
}

📁 File Organization

Smart Workspace Search: The server automatically finds MDF files in your project:

your-project/
├── data.mf4              # ✅ Found by filename
├── data/
│   └── test.mf4          # ✅ Found in data/ folder
├── measurements/
│   └── run1.mf4          # ✅ Found in measurements/ folder
├── test_data/
├── examples/
└── samples/

Usage Examples:

• "data.mf4" → Searches workspace automatically
• "./data/test.mf4" → Relative path from current directory
• "/absolute/path/file.mf4" → Full absolute path
• Case insensitive: "DATA.MF4" finds "data.mf4"

🔄 Staying Current

Always use latest version by adding @latest to your IDE configuration:

{
  "mcpServers": {
    "mdf": {
      "command": "uvx",
      "args": ["mcp-server-mdf@latest"]
    }
  }
}

Check version: uvx mcp-server-mdf@latest --version

📊 Usage Examples

Open and Analyze MDF Files

User: Open the measurement file at /data/test_drive.mf4
Assistant: I'll open that MDF file for you.

[Opens file]
Successfully opened test_drive.mf4:
- Session ID: mdf_a3b2c1d4
- Version: 4.10
- Channels: 847
- Duration: 1823.4 seconds

List and Search Channels

User: What temperature channels are available?
Assistant: Let me search for temperature-related channels.

Found 23 temperature channels:
- Engine_Temp (°C) - Engine coolant temperature
- Oil_Temp (°C) - Engine oil temperature
- Ambient_Temp (°C) - Outside air temperature

Analyze and Plot Signals

User: Show me the engine speed statistics and plot it
Assistant: I'll analyze the engine speed signal.

Engine Speed Analysis:
- Mean: 2,847 RPM
- Max: 6,234 RPM
- Std Dev: 1,123 RPM

[Shows time-series plot of engine speed]

🛠️ Available Tools

Session Management

• open_mdf - Open an MDF file
• close_mdf - Close a session
• list_sessions - Show active sessions
• get_file_info - Get file metadata

Data Access

• list_channels - List available channels
• mdf_get - Extract single channel data
• mdf_select - Extract multiple channels
• mdf_get_master - Get time channel data

Analysis

• calculate_statistics - Compute signal statistics
• plot_signals - Create visualizations
• mdf_to_dataframe - Convert to pandas DataFrame

Data Manipulation

• mdf_cut - Extract time slice
• mdf_filter - Filter specific channels
• mdf_resample - Change sampling rate

Export

• mdf_export - Export to various formats
• mdf_convert - Convert between MDF versions
• mdf_save - Save modified file

🐳 Docker Deployment (Alternative)

Build Image

docker build -t mcp-server-mdf .

Run Container

# Basic run
docker run -it --rm mcp-server-mdf

# With volume mount for data
docker run -it --rm -v /path/to/mdf/files:/data mcp-server-mdf

# With custom environment
docker run -it --rm -e MAX_SESSIONS=20 mcp-server-mdf

MCP Configuration for Docker

{
  "mcpServers": {
    "mdf": {
      "command": "docker",
      "args": ["run", "--rm", "-i", "-v", "/path/to/data:/data", "mcp-server-mdf"]
    }
  }
}

🧪 Testing

# Run tests
pytest tests/

# Test server manually
python tests/manual_test.py

📁 Project Structure

mdfmcp/
├── src/mdfmcp/
│   ├── __init__.py
│   └── server.py          # Main MCP server
├── tests/
│   ├── conftest.py
│   ├── manual_test.py
│   └── test_server.py
├── examples/
│   ├── basic_usage.py
│   └── test_data_generator.py
├── Dockerfile
├── requirements.txt
├── pyproject.toml
└── README.md

🔧 Development

Setup Development Environment

# Create virtual environment
python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

# Install dependencies
pip install -r requirements.txt

# Install in development mode
pip install -e .

Code Quality

# Format code
black src/

# Lint
ruff src/

# Type checking
mypy src/

🚨 Troubleshooting

Common Issues

1. Memory errors with large files

   • Use memory="low" when opening files
   • Reduce concurrent sessions

2. Cannot find channels

   • Channel names are case-sensitive
   • Use regex patterns for flexible searching

3. Docker build fails

   • Ensure Docker is running
   • Check Dockerfile syntax

🙏 Acknowledgments

• Built on asammdf by Daniel Hrisca (LGPL v3+)
• Uses the Model Context Protocol by Anthropic
• Matplotlib for plotting capabilities
• Pandas and NumPy for data processing

📄 License

This project is licensed under the MIT License - see the LICENSE file for details.

Dependencies: This project uses asammdf which is licensed under LGPL v3+. The asammdf library remains a separate component and is not modified by this project.