Xraylib MCP Server

xraylib MCP Server

A Model Context Protocol (MCP) server that provides access to xraylib X-ray interaction data through a standardized interface. Query cross-sections, fluorescence lines, edge energies, and more from any MCP-compatible client.

Table of Contents

• Features
• Installation
• Usage
• As a standalone server
• With Claude Desktop
• With VS Code
• With Claude Code
• As a development server
• Using Docker
• Development
• License
• Contributing

Features

This server exposes 104 tools organized into the following categories:

Utility tools

• AtomicNumberToSymbol / SymbolToAtomicNumber -- convert between atomic numbers and element symbols
• AtomicWeight -- atomic weight (g/mol)
• ElementDensity -- element density (g/cm3)
• ElectronConfig -- electron configuration for a given shell
• CompoundParser -- parse chemical formulas (e.g. SiO2, Ca5(PO4)3F)
• Atomic_Factors -- atomic scattering factors f0, f', f''

Line, edge, and shell properties

• LineEnergy / EdgeEnergy -- fluorescence line and absorption edge energies (keV)
• FluorYield / JumpFactor / RadRate -- fluorescence yields, jump factors, radiative rates
• AtomicLevelWidth -- natural widths of atomic levels (keV)

Cross-sections (element)

• CS_Total, CS_Photo, CS_Rayl, CS_Compt, CS_Energy, CS_KN -- mass cross-sections (cm2/g)
• CSb_Total, CSb_Photo, CSb_Rayl, CSb_Compt -- atomic cross-sections (barn/atom)

Fluorescence cross-sections

• CS_FluorLine / CSb_FluorLine -- line fluorescence cross-sections
• CS_FluorShell / CSb_FluorShell -- shell fluorescence cross-sections
• Kissel photoionization variants with full, radiative, nonradiative, and no cascade options

Differential cross-sections

• DCS_Rayl / DCS_Compt and barn/atom variants -- unpolarized differential cross-sections
• DCSP_Rayl / DCSP_Compt and barn/atom variants -- polarized differential cross-sections

Scattering factors

• FF_Rayl / SF_Compt -- Rayleigh form factor and Compton scattering function
• MomentTransf / ComptonEnergy -- momentum transfer and Compton-scattered photon energy
• Fi / Fii -- anomalous scattering factors
• ComptonProfile / ComptonProfile_Partial -- Compton profiles (total and per-shell)

Auger and Coster-Kronig transitions

• AugerRate / AugerYield -- Auger transition rates and yields
• CosKronTransProb -- Coster-Kronig transition probabilities

Compound cross-sections

• All CS/CSb, DCS/DCSb, and DCSP/DCSPb variants for compounds (by chemical formula)
• Kissel photoionization variants for compounds

Refractive index

• Refractive_Index_Re / Refractive_Index_Im -- real and imaginary parts of the refractive index

NIST compounds

• GetCompoundDataNISTByName / GetCompoundDataNISTByIndex / GetCompoundDataNISTList -- access the built-in NIST compound database

Radionuclide data

• GetRadioNuclideDataByName / GetRadioNuclideDataByIndex / GetRadioNuclideDataList -- access the built-in radionuclide database (X-ray lines, intensities, gamma energies)

Constant listings

• ListLineConstants / ListShellConstants / ListTransitionConstants / ListAugerConstants / ListNISTCompoundConstants -- enumerate valid constant names

Installation

Using uv (recommended)

uv tool install xraylib-mcp-server

Using pip

pip install xraylib-mcp-server

Usage

As a standalone server

# Run with stdio transport (for Claude Desktop, etc.)

xraylib-mcp-server

Run with HTTP transport

xraylib-mcp-server --transport http --port 8000

Run with SSE transport

xraylib-mcp-server --transport sse --port 8000

With Claude Desktop

Add to your Claude Desktop configuration:

{

"mcpServers": { "xraylib": { "command": "uvx", "args": ["xraylib-mcp-server"] } } }

Or using the pre-built Docker image:

{

"mcpServers": { "xraylib": { "command": "docker", "args": ["run", "-i", "--rm", "ghcr.io/tschoonj/xraylib-mcp-server:latest"] } } }

With VS Code

Add to your VS Code settings (.vscode/settings.json or user settings):

{

"mcp.servers": { "xraylib": { "command": "uvx", "args": ["xraylib-mcp-server"] } } }

Or using the pre-built Docker image:

{

"mcp.servers": { "xraylib": { "command": "docker", "args": ["run", "-i", "--rm", "ghcr.io/tschoonj/xraylib-mcp-server:latest"] } } }

With Claude Code

Add the server using the CLI:

claude mcp add xraylib -- uvx xraylib-mcp-server

Or using the pre-built Docker image:

claude mcp add xraylib -- docker run -i --rm ghcr.io/tschoonj/xraylib-mcp-server:latest

As a development server

# Run in development mode with MCP inspector

uv run mcp dev src/xraylib_mcp_server/server.py

Using Docker

Pre-built images from GitHub Container Registry

# Pull the latest image

docker pull ghcr.io/tschoonj/xraylib-mcp-server:latest

Run with stdio transport

docker run -i --rm ghcr.io/tschoonj/xraylib-mcp-server:latest

Run with HTTP transport on port 8000

docker run --rm -p 8000:8000 ghcr.io/tschoonj/xraylib-mcp-server:latest xraylib-mcp-server --transport http --port 8000

Use a specific version

docker pull ghcr.io/tschoonj/xraylib-mcp-server:0.1.0 docker run -i --rm ghcr.io/tschoonj/xraylib-mcp-server:0.1.0

Local development with Docker

# Build the Docker image locally

docker build -t xraylib-mcp-server .

Run with stdio transport

docker run -i --rm xraylib-mcp-server

Run with HTTP transport on port 8000

docker run --rm -p 8000:8000 xraylib-mcp-server xraylib-mcp-server --transport http --port 8000

Development

Setup

# Clone the repository

git clone https://github.com/tschoonj/xraylib-mcp-server.git cd xraylib-mcp-server

Install development dependencies

uv sync --dev

Running tests

# Run all tests

uv run pytest

Run with coverage

uv run pytest --cov=src/xraylib_mcp_server --cov-report=html

Code quality

# Lint

uv run ruff check .

Format

uv run ruff format .

Type check

uv run mypy src/ --ignore-missing-imports

License

BSD 3-Clause License -- see LICENSE for details.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests for new functionality
5. Run the test suite
6. Submit a pull request