rucio-mcp v0.9.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 <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"
      }
    }
  }
}

HTTP mode (multi-user, OIDC)

For sites that support OIDC (e.g. the ESCAPE Virtual Research Environment), rucio-mcp can run as a hosted OAuth 2.1 Authorization Server proxy — one server for many users with no IAM registration required:

rucio-mcp serve \
  --transport http \
  --site escape \
  --resource-url https://rucio-mcp.example.com \
  --host 0.0.0.0 \
  --port 8000

Each site is mounted under {resource-url}/site/{name}/. Configure your MCP client with the site URL:

{
  "mcpServers": {
    "rucio-escape": {
      "type": "http",
      "url": "https://rucio-mcp.example.com/site/escape/"
    }
  }
}

See docs/oauth-setup.md for the full setup guide.

Shared-secret HTTP mode (single pre-authenticated client)

To expose a single pre-authenticated instance (e.g. an x509/VOMS-proxy identity on a service host) over HTTP without the per-user OIDC bridge, start the server with --shared-secret (or RUCIO_MCP_SHARED_SECRET). It serves one env-built client (like stdio, honoring --auth-type) gated by a server-wide static bearer:

export RUCIO_ACCOUNT=<your_account>
voms-proxy-init -voms atlas
rucio-mcp serve \
  --transport http \
  --site atlas \
  --auth-type x509 \
  --shared-secret "$(openssl rand -hex 32)" \
  --host 0.0.0.0 \
  --port 9000

Clients send the secret as a bearer token (any other value → 401):

{
  "mcpServers": {
    "rucio-atlas": {
      "type": "http",
      "url": "http://host:9000/site/atlas/",
      "headers": { "Authorization": "Bearer <secret>" }
    }
  }
}

This mode serves a single --site and bypasses the OAuth bridge entirely (no /authorize, /token, or /register). See docs/configuration.md for details.

Broker HTTP mode (per-user x509 via the AF credential broker)

For Analysis Facility deployments behind af-mcp-platform's aggregator, --broker-url (or RUCIO_MCP_BROKER_URL) starts the server in broker mode: every request must carry a broker-issued identity JWT (verified against the broker's JWKS), and each tool call redeems the caller's own VOMS proxy from the broker to authenticate to Rucio via x509_proxy. The server holds no Rucio credential of its own, and the redeemed proxy file is deleted as soon as the per-call client has authenticated:

rucio-mcp serve \
  --transport http \
  --site atlas \
  --broker-url https://mcp.af.example.edu \
  --broker-audience rucio-mcp-atlas \
  --host 0.0.0.0 \
  --port 9000

Requires the broker extra (pip install 'rucio-mcp[broker]'). Like shared-secret mode, broker mode serves a single --site and has no OAuth bridge. See docs/configuration.md for details and the platform-side configuration.

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": {
    "rucio-escape": {
      "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

Requests and transfers

Accounts and quotas

Subscriptions

Locks

Scopes

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?"