Root MCP Server

🚀 root_mcp_server: MCP Server for ROOT

Model Context Protocol server for executing Python and C++ code with PyROOT

This project is a minimal MCP (Model Context Protocol) server that enables LLMs and other MCP clients to directly execute Python and C++ code using PyROOT, without relying on HTTP endpoints or external APIs.

🚀 Quick Start

The root_mcp_server allows LLMs and other MCP clients to execute Python and C++ code directly using PyROOT. You can start using it through different methods such as VS Code, command line, or programmatically.

✨ Features

• Direct Python execution: Automatically run Python code with PyROOT available.
• Direct C++ execution: Execute C++ code via ROOT's cling interpreter.
• In-process: All code runs within the same process (no subprocess isolation).
• Error detection: Automatically detect C++ compilation errors through return codes and stderr.
• Console logging: Display pretty-printed code execution results in the MCP console.
• Graphics support: Support TCanvas and ROOT graphics objects with event loop support.

🏗️ Architecture

The following is the architecture diagram for the root_mcp_server project, which visually represents the components and their interactions.

Component Description

• MCP Client (VS Code / CLI / Programmatic): Connects to the MCP server and sends execution requests. Clients can be interactive (e.g., VS Code + Copilot Chat) or scripted CLI clients.
• FastMCP Server: Receives MCP tool calls (root_python, root_cpp) and dispatches them to the in-process executor.
• RootExecutor (in-process PyROOT): Runs Python or C++ code with the ROOT runtime, manages graphics mode, and can expose an embedded HTTP server (THttpServer) for interactive canvases.
• ROOT Web Canvas (THttpServer / JSROOT): When graphics are enabled, canvases created in the ROOT session are accessible via the embedded HTTP server. Clients can open the provided URL to interactively inspect plots.
• Artifacts & Outputs: Execution results (stdout/stderr and error metadata) are returned to the MCP client. Interactive canvases are accessible via the HTTP endpoint.

This architecture ensures low-latency execution by running ROOT in-process while providing a web-based approach for interactive visualization.

📦 Installation

Prerequisites

• ROOT (6.x or later) with PyROOT enabled
• Python 3.10+

Install the Package

pip install -e .

💻 Usage Examples

Option 1: VS Code with GitHub Copilot Chat

The simplest way to use this MCP server is through VS Code with GitHub Copilot Chat.

Step 1: Install the GitHub Copilot Chat Extension

Ensure that you have installed the GitHub Copilot Chat extension in VS Code.

Step 2: Configure the MCP Server in VS Code

Add the MCP server configuration to your VS Code settings. Open your settings.json (Ctrl/Cmd + Shift + P → "Preferences: Open User Settings (JSON)") and add the following:

{
  "github.copilot.chat.codeGeneration.instructions": [
    {
      "text": "Use ROOT MCP server for data analysis"
    }
  ],
  "mcp.servers": {
    "root/mcp-server": {
      "type": "stdio",
      "command": "root_mcp_server",
      "args": []
    }
  }
}

Important: Replace /path/to/ROOT/build/bin/thisroot.sh with the actual path to your ROOT installation's thisroot.sh script.

Step 3: Use in Copilot Chat

Once configured, you can use the MCP tools in GitHub Copilot Chat:

@workspace Use #root_python to execute Python code with PyROOT

@workspace Use #root_cpp to execute C++ code with ROOT

The server will automatically log the executed code and results to the MCP console (visible in VS Code's Output panel).

Option 2: Command Line

Start the MCP server directly:

root_mcp_server

Option 3: Programmatic Usage

from mcp.client.stdio import stdio_client, StdioServerParameters
from mcp.client.session import ClientSession

server_params = StdioServerParameters(
    command="bash",
    args=["-lc", "source /path/to/thisroot.sh && python3 -m root_mcp_server.cli"],
    env=None
)

async with stdio_client(server_params) as (read, write):
    async with ClientSession(read, write) as session:
        await session.initialize()

        # Execute Python code
        result = await session.call_tool("root_python", arguments={
            "code": "import ROOT; print(ROOT.gROOT.GetVersion())"
        })
        print(result)

📚 Documentation

Available Tools

The server exposes two MCP tools:

1. root_python

Execute Python code with ROOT automatically available in scope.

Arguments:

• code (string): Python code to execute

Returns:

{
  "ok": boolean,
  "stdout": string,
  "stderr": string,
  "error": string | null,
  "error_type": string | null
}

Example:

code = """
import ROOT
h = ROOT.TH1F("h", "Gaussian", 100, -5, 5)
for i in range(10000):
    h.Fill(ROOT.gRandom.Gaus(0, 1))
print(f"Mean: {h.GetMean():.3f}")
"""

2. root_cpp

Execute C++ code via ROOT's cling interpreter.

Arguments:

• code (string): C++ code to execute

Returns:

{
  "ok": boolean,
  "stdout": string,
  "stderr": string,
  "error": string | null,
  "error_type": string | null
}

Example:

TH1F* h = new TH1F("h", "Gaussian;X;Y", 100, -5, 5);
for(int i=0; i<10000; i++) h->Fill(gRandom->Gaus(0,1));
TCanvas* c = new TCanvas("c", "Canvas", 900, 600);
h->Draw();
c->Update();
std::cout << "Mean: " << h->GetMean() << std::endl;

Features in Detail

Error Detection

The server automatically detects C++ compilation errors by:

• Checking the return code from ROOT.gInterpreter.ProcessLine()
• Scanning stderr for error keywords (error:, Error:, fatal error:)

Errors are reported with ok=false and detailed error messages.

Console Logging

All code execution is logged to stderr (MCP console) with:

• Pretty-printed code with line numbers
• Execution status (✓ success / ❌ failure)
• Complete stdout, stderr, and error details

Example output:

============================================================
EXECUTING PYTHON CODE:
  1 | import ROOT
  2 | print(ROOT.gROOT.GetVersion())
============================================================
✓ EXECUTION SUCCESS
STDOUT:
6.39/01

Graphics Support

The server initializes TApplication and supports ROOT graphics:

• TCanvas windows (batch mode can be disabled)
• Histogram plotting
• ROOT event loop for interactive graphics
• Object persistence to prevent garbage collection

🔧 Technical Details

Development

Running Tests

# Test basic functionality
python test_mcp_client.py

# Test persistent graphics
python test_persistent_window.py

# Test histogram creation
python test_histogram.py

Project Structure

root_mcp_server/
├── root_mcp_server/
│   ├── __init__.py
│   ├── cli.py          # Entry point
│   ├── executor.py     # Code execution 
│   └── server.py       # MCP server definition
├── test_mcp_client.py
├── test_persistent_window.py
├── test_histogram.py
└── README.md

📄 License

See the LICENSE file.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Acknowledgments

• Built with the Model Context Protocol
• Powered by ROOT from CERN