Ami

Actions Status Documentation Status

PyPI version PyPI platforms

GitHub Discussion

Coverage

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

Available tools

AMI queries

Tool	Description
ami_execute	Execute any AMI command string (primary power tool)
ami_get_dataset_info	Get metadata for a dataset (nFiles, nEvents, status, etc.)
ami_get_dataset_prov	Get provenance chain with lineage summary; filter by data type
ami_list_datasets	Search for datasets by name pattern (supports % wildcards)

PMG hashtags

Tool	Description
ami_search_by_hashtags	Find datasets by hashtag combination (e.g. WeakBoson/Vjets/Baseline)
ami_get_dataset_hashtags	Look up PMGL1–PMGL4 classification for a dataset

Physics metadata

Tool	Description
ami_get_physics_params	Get cross-section (nb→pb converted), filter efficiency, k-factor from AMI
ami_get_ami_tag	Get AMI processing tag info; accepts tag chains like e8351_s3681_r13144

Cross-section database

Tool	Description
ami_list_xsec_databases	List available PMGxsecDB_*.txt files
ami_lookup_xsec	Look up DSID cross-section, filter eff, k-factor in xsec DB

Validation

Tool	Description
ami_validate_sample	Check hashtag classification and compare metadata to xsec DB

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