Skip to main content

ami-mcp v0.4.0

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.11+
  • 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

Tool Description Read/write
ami_execute Execute any AMI command string (primary power tool) read-only
ami_get_dataset_info Get metadata for a dataset (nFiles, totalEvents, status, etc.) read-only
ami_get_datasets_info Batch metadata lookup for multiple datasets (one AMI query per catalog) read-only
ami_get_dataset_prov Get provenance chain with lineage summary; filter by data type read-only
ami_list_datasets Search for datasets by name pattern (supports % wildcards) read-only
ami_list_fields List the valid field names (type, description) of an AMI entity read-only

PMG hashtags

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

Physics metadata

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

Cross-section database

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

Validation

Tool Description Read/write
ami_validate_sample Check hashtag classification and compare metadata to xsec DB read-only

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

Metadata

Release files for ami-mcp 0.4.0

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for ami-mcp 0.4.0
File Size Uploaded Provenance Actions
ami_mcp-0.4.0.tar.gz 186.3 kB With provenance Details for ami_mcp-0.4.0.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for ami-mcp 0.4.0
File Interpreter ABI Platform Actions
ami_mcp-0.4.0-py3-none-any.whl Python 3 none any Details for ami_mcp-0.4.0-py3-none-any.whl

Total release size: 249.6 kB

Release files / ami_mcp-0.4.0.tar.gz

Download URL ami_mcp-0.4.0.tar.gz
Size 186.3 kB
Tags Source
SHA-256 checksum
How to use checksums
7c7f54ec102d2fd4d1863514e1a22b223b01f2b9d1a2851933b76497f38f4ce4
BLAKE2b-256 checksum
How to use checksums
6217caaaa0a66a724b6b7f1b333ffd2597b2f2526520c087ff7bd8c9841d36a1
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Release files / ami_mcp-0.4.0-py3-none-any.whl

Download URL ami_mcp-0.4.0-py3-none-any.whl
Size 63.3 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f4ded4a713d2e7a65c9043850f753fc9b1d365f1813d2625aece219217219339
BLAKE2b-256 checksum
How to use checksums
ecffaabbb3d2d957a798e35138ea6a339bdace752725e990e2e3874a18cb4a27
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

Security for ami-mcp 0.4.0

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for ami_mcp-0.4.0.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 15, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page