XRootD MCP Server

A Model Context Protocol (MCP) server that provides access to XRootD file systems. This server allows LLMs to interact with XRootD servers to list directories, read file metadata, access file contents, and more.

📚 View Full Documentation

Features

• List directories: Browse XRootD file system hierarchy

• File metadata: Get detailed information about files (size, modification time, permissions)

• Read file contents: Access file data from XRootD servers with byte-range support

• File operations: Check file existence, calculate directory sizes

• Search & filtering: Find files by pattern (glob/regex), filter by size/date

• Statistics & analytics: Comprehensive directory statistics and usage reports

• Campaign discovery: List available production campaigns and datasets

• Recent changes: Track newly added files and monitor production progress

• ROOT file analysis: Inspect ROOT file structure, extract metadata, analyze events and collections

• Dataset aggregation: Aggregate event statistics across multiple ROOT files

• Protocol support: Connect to XRootD servers via root:// protocol

Related MCP server: rucio-mcp

Installation

Using Docker (Recommended)

docker pull ghcr.io/eic/xrootd-mcp-server:latest

docker run -i --rm \
  -e XROOTD_SERVER="root://dtn2304.jlab.org:8443" \
  -e XROOTD_BASE_DIR="/jlab-osdf-ro/eic/EPIC/volatile" \
  ghcr.io/eic/xrootd-mcp-server:latest

See Docker Usage Guide for detailed instructions.

From Source

npm install
npm run build

Configuration

Set the XRootD server URL using the XROOTD_SERVER environment variable:

export XROOTD_SERVER="root://dtn2304.jlab.org:8443"

Optionally, set a base directory to restrict access and simplify paths:

export XROOTD_BASE_DIR="/jlab-osdf-ro/eic/EPIC/volatile"

When XROOTD_BASE_DIR is set:

• Relative paths are resolved relative to the base directory

• Absolute paths must be within the base directory (access control)

• For example, with base /jlab-osdf-ro/eic/EPIC/volatile, the path EVGEN refers to /jlab-osdf-ro/eic/EPIC/volatile/EVGEN

Transports

The server speaks stdio by default (for clients that spawn it themselves). Two HTTP transports are available via MCP_TRANSPORT:

# Streamable HTTP: MCP endpoint at http://127.0.0.1:9102/mcp
MCP_TRANSPORT=http XROOTD_SERVER="root://dtn2304.jlab.org:8443" node build/src/index.js

# Legacy SSE: endpoints at /sse and /messages
MCP_TRANSPORT=sse XROOTD_SERVER="root://dtn2304.jlab.org:8443" node build/src/index.js

MCP_HOST (default 127.0.0.1) and MCP_PORT (default 9102) control the bind address. The server binds loopback by default; binding any other address prints a warning because the tools carry no authentication.

An HTTP client config then looks like:

{
  "mcpServers": {
    "xrootd": {
      "type": "http",
      "url": "http://127.0.0.1:9102/mcp"
    }
  }
}

Caching

Directory listing results are cached for improved performance:

export XROOTD_CACHE_ENABLED=true      # default: true
export XROOTD_CACHE_TTL=60            # minutes, default: 60
export XROOTD_CACHE_MAX_SIZE=1000     # max entries, default: 1000

The cache uses a time-based expiration strategy (TTL):

• Directory listings are cached in memory

• Cache entries expire after the configured TTL

• Automatic cleanup removes expired entries every 15 minutes

• LRU eviction when cache size exceeds 1000 entries

Note: Cached data may be up to TTL minutes old. For production data that changes infrequently, a 60-minute TTL provides good performance with acceptable staleness.

Usage

With MCP Client

Add to your MCP client configuration:

{
  "mcpServers": {
    "xrootd": {
      "command": "node",
      "args": ["/path/to/xrootd-mcp-server/build/index.js"],
      "env": {
        "XROOTD_SERVER": "root://dtn2304.jlab.org:8443",
        "XROOTD_BASE_DIR": "/jlab-osdf-ro/eic/EPIC/volatile",
        "XROOTD_CACHE_ENABLED": "true",
        "XROOTD_CACHE_TTL": "60"
      }
    }
  }
}

Available Tools

Basic File Operations:

• list_directory: List contents of an XRootD directory

• get_file_info: Get detailed metadata about a file

• read_file: Read contents of a file (with optional byte range)

• check_file_exists: Check if a file or directory exists

• get_directory_size: Calculate total size of a directory

Advanced Search & Analysis:

• search_files: Search for files by glob pattern or regex

• list_directory_filtered: List directory with advanced filtering (size, date, extension, pattern)

• find_recent_files: Find files modified within a time period

• get_statistics: Get comprehensive statistics about files in a directory

Campaign & Dataset Discovery:

• list_campaigns: List available production campaigns

• list_datasets: List datasets within a specific campaign

• summarize_recent_changes: Summarize files added in a time period with detailed statistics

Timeouts and truncation

Every tool except list_servers takes timeout (seconds; default 120, or XROOTD_TOOL_TIMEOUT). On expiry the tool returns Error: <tool> did not finish within N s. ... with what to try (deeper path, recursive: false, smaller range, or retry once later: the xrootd command keeps running until it finishes). Any list in a result stops at 1000 entries and a sibling <key>Truncated field reads truncated: N of M entries; <how to narrow the call>; read_file returns at most 1 MB per call and appends [truncated: N of M bytes; ...]. Expected failures (unknown path, unknown server, HTTP access needing allow_copy) come back as Error: ... text with isError set, not as protocol errors.

Development

# Build
npm run build

# Watch mode
npm run watch

Requirements

• Node.js 18 or higher

• Access to an XRootD server

• xrdfs command-line tool installed (from xrootd-client package)

License

MIT