rucio-mcp v0.3.0

An MCP server that exposes Rucio distributed data management operations as tools for LLMs. Designed for ATLAS physicists working with grid data on analysis facilities, but usable with any Rucio instance.

What it does

rucio-mcp lets Claude (or any MCP-compatible LLM) query and manage your Rucio data directly:

• Find data: search for datasets/containers by pattern, list files, browse DID hierarchies

• Check replicas: see where data is physically stored, which sites have a dataset, generate access URLs

• Manage rules: list, create, update, move, approve, and delete replication rules

• Monitor: check RSE storage usage, account quotas, proxy certificate validity

All tool descriptions include ATLAS dataset naming conventions so the LLM understands scope formats, AMI tags, and DID structure without extra prompting.

Installation

pip install rucio-mcp

Or with pixi (recommended for ATLAS facilities):

pixi add rucio-mcp

Requirements

• Python 3.10+

• A configured Rucio environment (rucio.cfg and valid authentication)

• For x509 proxy auth: a valid VOMS proxy (voms-proxy-init -voms atlas)

Quick start

1. Set up authentication

x509 proxy (most common at ATLAS sites):

voms-proxy-init -voms atlas
export RUCIO_ACCOUNT=<your_atlas_account>
export RUCIO_AUTH_TYPE=x509_proxy
export RUCIO_HOME=/path/to/rucio-clients   # directory containing etc/rucio.cfg

When installed via pixi (recommended):

ca-policy-lcg is included as a dependency and sets X509_CERT_DIR automatically to the certificates bundled in the conda environment. No manual configuration needed.

If you run into an error about expired CRLs

Error: Certificate verification failed.
sslutils.c:1911:error:40000405:lib(128)::outdated CRL found, revoking all certs till you get new CRL
sslutils.c:2106:error:40000411:lib(128)::certificate validation error: CRL has expired

then you need to run the following to refresh the CRLs:

pixi run sh -c '$X509_CERT_DIR/refresh_crls.sh'

or

bash
pixi exec --with rucio-mcp sh -c '$X509_CERT_DIR/refresh_crls.sh'

On CVMFS-based facilities without pixi (e.g. UChicago Analysis Facility):

voms-proxy-init -voms atlas
export RUCIO_ACCOUNT=<your_atlas_account>
export RUCIO_AUTH_TYPE=x509_proxy
export X509_CERT_DIR=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates
export RUCIO_HOME=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/x86_64/rucio-clients/35.6.0

2. Test the server

rucio-mcp serve

The server speaks MCP over stdio. Configure your MCP client to launch it.

3. Configure Claude Code

Add to your .mcp.json (project) or ~/.claude.json (global).

The name atlas lets you tell Claude "use the atlas rucio server" — useful when you have multiple Rucio instances configured.

With pixi (X509_CERT_DIR set automatically by ca-policy-lcg):

{
  "mcpServers": {
    "atlas": {
      "type": "stdio",
      "command": "pixi",
      "args": [
        "run",
        "--manifest-path",
        "/path/to/rucio-mcp",
        "rucio-mcp",
        "serve"
      ],
      "env": {
        "RUCIO_AUTH_TYPE": "x509_proxy",
        "RUCIO_ACCOUNT": "youraccount",
        "RUCIO_HOME": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/x86_64/rucio-clients/35.6.0"
      }
    }
  }
}

Without pixi (if you have CVMFS + ATLAS, use the path below; otherwise point X509_CERT_DIR at your local CA bundle):

{
  "mcpServers": {
    "atlas": {
      "type": "stdio",
      "command": "rucio-mcp",
      "args": ["serve"],
      "env": {
        "RUCIO_AUTH_TYPE": "x509_proxy",
        "RUCIO_ACCOUNT": "youraccount",
        "X509_CERT_DIR": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates",
        "RUCIO_HOME": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/x86_64/rucio-clients/35.6.0"
      }
    }
  }
}

4. Configure Claude Desktop

Add to ~/Library/Application Support/Claude/claude_desktop_config.json (macOS) or %APPDATA%\Claude\claude_desktop_config.json (Windows).

With pixi:

{
  "mcpServers": {
    "atlas": {
      "type": "stdio",
      "command": "pixi",
      "args": [
        "run",
        "--manifest-path",
        "/path/to/rucio-mcp",
        "rucio-mcp",
        "serve"
      ],
      "env": {
        "RUCIO_AUTH_TYPE": "x509_proxy",
        "RUCIO_ACCOUNT": "youraccount",
        "RUCIO_HOME": "/path/to/rucio-clients"
      }
    }
  }
}

Without pixi (if you have CVMFS + ATLAS, use the path below; otherwise point X509_CERT_DIR at your local CA bundle):

{
  "mcpServers": {
    "atlas": {
      "type": "stdio",
      "command": "rucio-mcp",
      "args": ["serve"],
      "env": {
        "RUCIO_AUTH_TYPE": "x509_proxy",
        "RUCIO_ACCOUNT": "youraccount",
        "X509_CERT_DIR": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates",
        "RUCIO_HOME": "/path/to/rucio-clients"
      }
    }
  }
}

Read-only mode

Start the server with --read-only to block all write operations. Tools that create, modify, or delete replication rules will return an error instead of executing.

rucio-mcp serve --read-only

Or in your MCP config:

{
  "mcpServers": {
    "atlas": {
      "command": "rucio-mcp",
      "args": ["serve", "--read-only"],
      "env": { "...": "..." }
    }
  }
}

Useful when you want the LLM to help explore data without the ability to accidentally create rules or modify existing ones.

Available tools

Connectivity

DID discovery

Replicas

Replication rules

RSEs and storage

Account

Example prompts

Once configured, you can ask Claude things like:

• "Find all DAOD_PHYS containers for mc20_13TeV DSID 700320"

• "Which sites have dataset X available and how complete is each replica?"

• "Create a rule to replicate this dataset to a US Tier-1 disk site for 30 days"

• "Is my proxy still valid? How long do I have left?"

• "Show me the replication rules for this container and their current states"

• "What's my storage quota at CERN-PROD_DATADISK?"