root-mcp 0.1.2

Production-grade MCP server for CERN ROOT file analysis

ROOT-MCP: AI-Powered HEP Analysis

ROOT-MCP empowers Large Language Models (LLMs) to natively understand and analyze CERN ROOT files.

By exposing a set of specialized tools via the Model Context Protocol (MCP), it turns Claude (and other MCP-compliant agents) into capable physics research assistants that can:

• Inspect ROOT file structures (Trees, Branches, Histograms)
• Analyze data distributions (Compute Histograms, Statistics)
• Compute kinematic quantities (invariant masses, angular correlations for Dalitz plots)
• Visualize results directly in the chat
• Filter data using physics cuts ("selections")

Why this matters: Instead of asking an LLM to "write a script" that you have to debug and run, you can ask the LLM to "Check the muon pT distribution in this file" and it will just do it.

---

Quick Start

1. Install

pip install root-mcp
# Optional: pip install "root-mcp[xrootd]" for remote file support

2. Configure

Create a config.yaml to tell the server where your data is:

resources:
  - name: "my_analysis"
    uri: "file:///Users/me/data"
    allowed_patterns: ["*.root"]

security:
  allowed_roots:
    - "/Users/me/data"

3. Run with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "root-mcp": {
      "command": "root-mcp",
      "env": {
        "ROOT_MCP_CONFIG": "/path/to/config.yaml"
      }
    }
  }
}

Documentation

• Full Documentation: The complete guide.
• Tool Reference: Detailed API definition for all tools.
• LLM Integration Guide: How to prompt and work with the agent.

Citation

If you use ROOT-MCP in your research, please cite:

@software{root_mcp,
  title = {ROOT-MCP: Production-Grade MCP Server for CERN ROOT Files},
  author = {Mohamed Elashri},
  year = {2025},
  url = {https://github.com/MohamedElashri/root-mcp}
}

License

MIT License - see LICENSE for details.