Rucio

Actions Status Documentation Status

PyPI version Conda-Forge PyPI platforms

GitHub Discussion

Coverage

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.

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

Tool	Description
rucio_ping	Check server connectivity and version
rucio_whoami	Show authenticated account info
rucio_voms_proxy_info	Show VOMS proxy certificate status and expiry

DID discovery

Tool	Description
rucio_list_dids	Search for datasets/containers by wildcard pattern
rucio_get_did	Get type, size, and timestamps for a DID
rucio_list_content	List immediate contents of a container or dataset
rucio_list_files	List all files within a DID
rucio_get_metadata	Retrieve metadata key-value pairs for a DID
rucio_list_parent_dids	Find containers that hold a given DID

Replicas

Tool	Description
rucio_list_replicas	Physical replica locations (PFNs) for files
rucio_list_dataset_replicas	Dataset availability summary across RSEs
rucio_list_container_replicas	Dataset replica summary aggregated across a container

Replication rules

Tool	Write?	Description
rucio_list_did_rules	—	List all rules for a specific DID
rucio_list_replication_rules	—	List rules globally, filtered by scope/account
rucio_get_replication_rule	—	Detailed info for a specific rule
rucio_list_rule_history	—	Full state history of rules for a DID
rucio_add_rule	✓	Create a new replication rule
rucio_delete_rule	✓	Delete a rule (optionally purge replicas)
rucio_update_rule	✓	Update lifetime, locked flag, comment, activity
rucio_reduce_rule	✓	Reduce the number of copies in a rule
rucio_move_rule	✓	Move a rule to a different RSE expression
rucio_approve_rule	✓	Approve a rule awaiting approval
rucio_deny_rule	✓	Deny a rule awaiting approval

RSEs and storage

Tool	Description
rucio_list_rses	List RSEs matching an expression
rucio_get_rse	Detailed configuration info for an RSE
rucio_list_rse_attributes	Key-value attributes for an RSE
rucio_get_rse_usage	Total, used, and free storage at an RSE
rucio_get_rse_limits	Configured space limits for an RSE
rucio_get_rse_protocols	Transfer protocols supported by an RSE
rucio_get_distance	Network distance (ranking) between two RSEs
rucio_list_transfer_limits	Global transfer limit policies by activity/RSE

Requests and transfers

Tool	Description
rucio_list_requests	Current transfer requests between two RSEs
rucio_list_requests_history	Historical transfer requests between two RSEs

Accounts and quotas

Tool	Description
rucio_list_accounts	List accounts, optionally filtered
rucio_get_account	Detailed info for a specific account
rucio_get_local_account_usage	Storage used per RSE for an account
rucio_get_local_account_limits	Storage quota limits for an account
rucio_list_account_rules	All replication rules owned by account

Subscriptions

Tool	Description
rucio_list_subscriptions	List subscriptions, optionally filtered
rucio_list_subscription_rules	Rules generated by a specific subscription

Locks

Tool	Description
rucio_get_dataset_locks	Locks on a specific dataset DID
rucio_get_dataset_locks_by_rse	All dataset locks at a specific RSE

Scopes

Tool	Description
rucio_list_scopes	List all available scopes
rucio_list_scopes_for_account	Scopes owned by a specific 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?"