ami-mcp v0.3.0

An MCP server that wraps ATLAS AMI (ATLAS Metadata Interface) and the PMG cross-section database, exposing them as tools for LLMs. Designed for ATLAS physicists who need to discover MC samples, look up cross-sections and filter efficiencies, and validate PMG hashtag classifications.

What it does

ami-mcp lets Claude (or any MCP-compatible LLM) query ATLAS metadata directly:

• Discover samples: search for MC datasets by PMG hashtag classification (WeakBoson/Vjets/Baseline), by name pattern, or by arbitrary AMI query
• Look up metadata: retrieve cross-sections, filter efficiencies, k-factors, dataset provenance, and AMI processing tag info
• Query cross-section DB: look up DSID entries in the PMG xsec database files (PMGxsecDB_mc16.txt, etc.)
• Validate samples: check hashtag classifications and compare metadata against the PMG cross-section database
• General queries: execute arbitrary AMI command strings formulated by the LLM using the ami://query-language resource as a guide

Installation

pip install ami-mcp

Or with pixi (recommended for ATLAS facilities):

pixi add ami-mcp

Requirements

• Python 3.10 or 3.11 (pyAMI requires <3.12)
• A valid VOMS proxy (voms-proxy-init -voms atlas)
• Grid CA certificates (available on CVMFS at ATLAS sites)

Quick start

1. Set up authentication

voms-proxy-init -voms atlas

When installed via pip (not pixi/conda-forge), also set X509_CERT_DIR. On CVMFS-based facilities (e.g. UChicago Analysis Facility, CERN lxplus):

export X509_CERT_DIR=/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates

When installed via pixi or conda-forge, ca-policy-lcg is included and sets X509_CERT_DIR automatically — no extra step needed.

2. Test the server

ami-mcp serve

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

3. Configure Claude Code

With pixi (recommended — X509_CERT_DIR is set automatically):

{
  "mcpServers": {
    "ami": {
      "type": "stdio",
      "command": "pixi",
      "args": ["run", "ami-mcp", "serve"],
      "env": {
        "ATLAS_PMGXSEC_PATH": "/cvmfs/atlas.cern.ch/repo/sw/database/GroupData/dev/PMGTools"
      }
    }
  }
}

With pip (must set X509_CERT_DIR manually):

{
  "mcpServers": {
    "ami": {
      "command": "ami-mcp",
      "args": ["serve"],
      "env": {
        "X509_CERT_DIR": "/cvmfs/atlas.cern.ch/repo/ATLASLocalRootBase/etc/grid-security-emi/certificates",
        "ATLAS_PMGXSEC_PATH": "/cvmfs/atlas.cern.ch/repo/sw/database/GroupData/dev/PMGTools"
      }
    }
  }
}

4. Configure Claude Desktop

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

{
  "mcpServers": {
    "ami": {
      "command": "ami-mcp",
      "args": ["serve"],
      "env": {
        "X509_CERT_DIR": "/path/to/ca-certificates",
        "ATLAS_PMGXSEC_PATH": "/path/to/PMGTools"
      }
    }
  }
}

Deploying on Kubernetes

A Helm chart at charts/ami-mcp deploys the server over HTTP transport in either shared-secret (server-managed VOMS proxy + static bearer) or AF-credential-broker (per-user proxies) mode. See Deploying with Helm for the full guide. For running the server directly on a facility (e.g. the UChicago Analysis Facility), see the contributor guide (CLAUDE.md).

Available tools

All tools are read-only (read_only_hint=true in their MCP tool annotations) and query the external ATLAS AMI service or a local cross-section database (open_world_hint=true); there is no tool that mutates AMI or facility state.

AMI queries

PMG hashtags

Physics metadata

Cross-section database

Validation

Example prompts

Once configured, you can ask Claude things like:

• "Find all Baseline WeakBoson/Vjets samples in mc21_13TeV"
• "What are the cross-section and filter efficiency for DSID 700320?"
• "Look up the hashtag classification for this EVNT dataset"
• "Validate these samples against the mc21 cross-section database"
• "Show me the provenance chain for this DAOD dataset"
• "What AMI tag e8351 corresponds to — which generator version?"