Xraylib Mcp Server

xraylib MCP Server

[CI] [Docker Image] [PyPI] [License: BSD-3-Clause]

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 transportxraylib-mcp-server --transport http --port 8000
# Run with SSE transportxraylib-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 inspectoruv run mcp dev src/xraylib_mcp_server/server.py

Using Docker

Pre-built images from GitHub Container Registry

# Pull the latest imagedocker pull ghcr.io/tschoonj/xraylib-mcp-server:latest
# Run with stdio transportdocker run -i --rm ghcr.io/tschoonj/xraylib-mcp-server:latest
# Run with HTTP transport on port 8000docker run --rm -p 8000:8000 ghcr.io/tschoonj/xraylib-mcp-server:latest xraylib-mcp-server --transport http --port 8000
# Use a specific versiondocker pull ghcr.io/tschoonj/xraylib-mcp-server:0.1.0docker run -i --rm ghcr.io/tschoonj/xraylib-mcp-server:0.1.0

Local development with Docker

# Build the Docker image locallydocker build -t xraylib-mcp-server .
# Run with stdio transportdocker run -i --rm xraylib-mcp-server
# Run with HTTP transport on port 8000docker run --rm -p 8000:8000 xraylib-mcp-server xraylib-mcp-server --transport http --port 8000

Development

Setup

# Clone the repositorygit clone https://github.com/tschoonj/xraylib-mcp-server.gitcd xraylib-mcp-server
# Install development dependenciesuv sync --dev

Running tests

# Run all testsuv run pytest
# Run with coverageuv run pytest --cov=src/xraylib_mcp_server --cov-report=html

Code quality

# Lintuv run ruff check .
# Formatuv run ruff format .
# Type checkuv 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