Getting started

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 <VO>)

Quick start

1. Set up authentication

x509 proxy (ATLAS sites):

voms-proxy-init -voms atlas
export RUCIO_ACCOUNT=<your_atlas_account>

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 X509_CERT_DIR=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates
export RUCIO_CONFIG=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/x86_64/rucio-clients/35.6.0/etc/rucio.cfg
rucio-mcp serve --site atlas --auth-type x509

x509 proxy (CMS sites):

voms-proxy-init -voms cms
export RUCIO_ACCOUNT=<your_cms_account>
rucio-mcp serve --site cms --auth-type x509

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 key name (rucio-atlas below) lets you tell Claude which Rucio server to use — useful when you have multiple Rucio instances configured. Choose any name you like.

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

{
  "mcpServers": {
    "rucio-atlas": {
      "type": "stdio",
      "command": "pixi",
      "args": [
        "run",
        "--manifest-path",
        "/path/to/rucio-mcp",
        "rucio-mcp",
        "serve",
        "--site",
        "atlas",
        "--auth-type",
        "x509"
      ],
      "env": {
        "RUCIO_ACCOUNT": "youraccount"
      }
    }
  }
}

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

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

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": {
    "rucio-atlas": {
      "type": "stdio",
      "command": "pixi",
      "args": [
        "run",
        "--manifest-path",
        "/path/to/rucio-mcp",
        "rucio-mcp",
        "serve",
        "--site",
        "atlas",
        "--auth-type",
        "x509"
      ],
      "env": {
        "RUCIO_ACCOUNT": "youraccount"
      }
    }
  }
}

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

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