root-mcp
About
MCP server for ROOT CERN files
Details
- Author
- mohamedelashri
- Categories
- Other
Jump to
Setup
Install root-mcp in your MCP client (Claude Desktop, Cursor, Windsurf, and others).
Repository: https://github.com/mohamedelashri/root-mcp
Follow the installation instructions in the repository README, then restart your MCP client.
Repository Mirror: This repository is mirrored toCERN GitLabfor CERN users. PyPI releases are published via GitHub Actions using attestation-based trusted publishing.
ROOT-MCPempowers Large Language Models (LLMs) to natively understand and analyze CERN ROOT files.
By exposing a set of specialized tools via theModel Context Protocol (MCP)or a token-efficientCLI interface, it turns Claude (and other MCP-compliant agents) into capable physics research assistants that can:
- InspectROOT file structures (Trees, RNTuples, Branches, Histograms)
- Analyzedata distributions (Compute Histograms, Statistics)
- Computekinematic quantities (Invariant Mass)
- Visualizeresults (Plot 1D/2D histograms directly)
- Filterdata 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 willjust do it.
ROOT-MCP providestwo waysto interact with ROOT files:
1. MCP Server (for Claude Desktop and MCP clients)
- Full JSON-RPC protocol support
- Structured input/output for programmatic use
- Best for: MCP-compliant LLM clients, automated workflows
- Human-readable output by default
- Simpler architecture (no server process)
- Best for: Direct LLM interaction, debugging, scripting
Both interfaces share the same backend and support all 17 analysis tools.
Optional: For remote file access via XRootD protocol:
pip install "root-mcp[xrootd]"
# MCP Server root-mcp --data-path /path/to/your/data # CLI (token-efficient) root-cli -d /path/to/your/data ls
export ROOT_MCP_DATA_PATH=/path/to/your/data
ROOT CLI (Recommended for LLM Interaction)
The CLI provides atoken-efficient, human-readable interface that provides significant token savings compared to the MCP JSON protocol.
# List files root-cli ls # Inspect a file root-cli inspect /data/sample.root # Create histogram with fit root-cli histogram /data/sample.root events muon_pt --bins 100 --fit gaussian # Read data with selection root-cli read /data/sample.root events met muon_pt --selection "met > 50" # Plot results root-cli plot1d /tmp/root_mcp/muon_pt_hist.json -o plot.png --title "Muon pT"
Ask your LLM:"Plot the muon pT distribution"
root-cli histogram /data/sample.root events muon_pt --bins 50 && \ root-cli plot1d /tmp/root_mcp/muon_pt_hist.json -o muon_pt.png --title "Muon pT Distribution"
Seedocs/skills/root-cli.mdfor complete command reference with examples.
# Core mode (lightweight, no scipy/matplotlib needed) root-mcp --data-path /data --mode core # Explicit stdio transport (same runtime as the compatibility default) root-mcp serve-stdio --data-path /data # Extended mode with native ROOT, restricted to one directory root-mcp --data-path /data --enable-root --allowed-root /data # Remote XRootD resource, no YAML needed root-mcp --resource cms=root://xrootd.cern.ch//store --allow-remote --mode extended # Docker / container — fully env-var driven ROOT_MCP_DATA_PATH=/data ROOT_MCP_MODE=extended ROOT_MCP_EXPORT_PATH=/exports root-mcp # Quiet server (only warnings+) with a cache increase root-mcp --data-path /data --log-level WARNING --cache-size 100
root-mcp serve-httpserves the MCP Streamable HTTP endpoint for central deployments. It requires explicit auth, Origin validation, restrictive central policy, and safe bind-address settings before it starts.
For shared deployments, start with the operator docs:docs/operator/central_deployment.mdanddocs/operator/security_checklist.md. Restrictive starter configs and Kubernetes manifests live inexamples/central/.
Operators can preview and apply export retention withroot-mcp cleanup-exports --config /etc/root-mcp/config.yaml --dry-run. The external HTTP smoke script atscripts/smoke_external_http_client.pystarts a temporary central server and checks it with the MCP Streamable HTTP client.
root-mcp init --permissive # creates config.yaml pre-filled with current directory
Manual config file— for persistent settings, remote resources, or native ROOT:
server: mode: "extended" # "core" or "extended" resources: - name: "my_analysis" uri: "file:///path/to/data" allowed_patterns: ["*.root"] security: allowed_roots: [] # empty = any local path is accessible (permissive)
Local-use warning: The permissiveallowed_roots: []default is intended for trusted local stdio sessions. Do not expose that configuration as a shared HTTP service; restrict roots and require an authenticated deployment profile before central or multi-user use.
- mode: "core"— Lightweight: file operations and basic statistics
- mode: "extended"— Full analysis: histograms, fitting, kinematics, correlations
Switch modes at runtime with theswitch_modetool — no restart required.
Add to yourclaude_desktop_config.json:
{ "mcpServers": { "root-mcp": { "command": "root-mcp", "args": ["--data-path", "/path/to/your/data"] } } }
{ "mcpServers": { "root-mcp": { "command": "root-mcp", "env": { "ROOT_MCP_CONFIG": "/path/to/config.yaml" } } } }
ROOT-MCP organizes analysis capabilities intoanalysis tiers:
- Core Mode: File I/O, data reading, and basic statistics
- Extended Mode: Full analysis capabilities including fitting, kinematics, and correlations
The mode is controlled via configuration, and the server automatically loads only the components you need. Runtime mode switching is also available.
ROOT-MCP can optionally integrate with a nativeROOT/PyROOTinstallation to unlock capabilities beyond whatuprootprovides:
- run_root_code: Execute arbitrary PyROOT/Python code and get structured results
- run_rdataframe: Compute histograms using ROOT's RDataFrame (no boilerplate needed)
- run_root_macro: Execute C++ ROOT macros viagROOT.ProcessLine
This feature isentirely optional— ROOT-MCP works fully without ROOT installed. When ROOT is available and enabled, these additional tools appear automatically.
Requirements: A working ROOT installation (viaconda-forge, system package, or binary tarball). ROOT is not pip-installable at this time.
Enable itby settingenable_root: truein yourconfig.yaml:
features: enable_root: true # Optional: tune execution settings root_native: execution_timeout: 60 working_directory: "/tmp/root_mcp_native"
Useget_server_infoto check ROOT availability at runtime:
{ "root_native_available": true, "root_native_enabled": true, "root_version": "6.32/02", "root_features": {"rdataframe": true, "roofit": true, "tmva": false} }
The full documentation site is built with Sphinx and covers installation, configuration, all 20 MCP tools, LLM integration patterns, and the developer guide with auto-generated API reference.
Read online: The docs are hosted atroot-mcp docs
pip install "root-mcp[docs]" ./scripts/build_docs.sh # open docs/_build/html/index.html
- User Guide— installation, quickstart, modes, configuration, LLM integration
- Tool Reference— complete catalogue of all tools and their JSON payloads
- CLI Reference— complete command reference for root-cli with examples
- Developer Guide— architecture, module overview, dev setup, contributing
- API Reference— auto-generated from source docstrings
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} }
Institutional research and manager diligence reports on hedge funds, venture capital and private equity managers. Summary of filings, personnel changes, media screening and social signals delivered to you in minutes.
AI-powered property zoning, buildability, and ADU eligibility analysis for any U.S. address via 20+ government data sources.
Deep fundamental data from SEC filings, including operational KPIs not found on Bloomberg, built for your financial AI agents.
Control anaerobic digestion modeling (ADM1) using natural language.
Search 3,500+ US universities, estimate admission chances, check financial aid by income bracket, and build balanced college lists. Free MCP server, no API key required. Data from IPEDS and College Scorecard
Eleven MCP servers for reproducible EPA SWMM stormwater modelling — building, simulation, calibration, GIS, climate scenarios, uncertainty, plotting, and modelling memory.
A Model Context Protocol (MCP) server that provides comprehensive access to the ALMA (Atacama Large Millimeter/submillimeter Array) archive through a clean, extensible architecture.
aTars MCP by aarna provides AI agents with structured access to crypto market signals, technical indicators, and sentiment analysis.
Deterministic Korean Saju / Chinese BaZi Four Pillars MCP server — Heavenly Stems, Earthly Branches, Day Master, five elements, and 0-100 compatibility. No AI, no API key.
Detect and audit AI bias across protected characteristics — demographic parity, equalized odds, disparate impact analysis
Sign in to leave a review
Use Google, GitHub, or an email account so ratings stay tied to real people.
No reviews posted yet.
