nds-mcp

Nuclear Data Services MCP server — offline SQLite-backed nuclear physics data for AI agents.

Provides standard-mode tools covering atomic masses (AME2020), nuclear properties (NUBASE2020), charge radii (IAEA + laser spectroscopy), energy levels and gamma transitions (ENSDF), light nuclei resonance data (TUNL, A=4–20), bibliographic references, JENDL-5 decay/cross-section data, EXFOR experimental data, CODATA fundamental constants, update checks, plus discovery/query helpers (nds_catalog, nds_schema, nds_query).

Quick Start

npx -y nds-mcp

The pre-built SQLite database (~85 MB) is automatically downloaded to ~/.nds-mcp/nds.sqlite on first launch. By default it downloads from this repo's GitHub Releases (override via NDS_DB_DOWNLOAD_URL). Release assets use a single compressed format: *.sqlite.gz (auto-decompressed after download).

Optional tools JENDL-5 / EXFOR use separate SQLite files and are auto-downloaded on demand. Maintainer ingest support also includes FENDL-3.2c and IRDFF-II optional SQLite files. CODATA is bundled inside nds.sqlite.

Using nds-mcp through AI agents

1. Register the server in your client using the same launch command as Quick Start (see Configuration for Cursor, Claude Code, VS Code, Codex, OpenCode, and others).
2. Ask questions in chat. The agent chooses MCP tools based on your request; you do not need to call tools manually.
3. Discovery workflow: start with nds_info (data versions, optional DB status) and nds_catalog (what is installed and how to query it). When one physical quantity appears in more than one source, tools return source-tagged values by default; see Cross-Source Rule.
4. Downloads: the main nds.sqlite file is fetched on first server startup (see Quick Start). Optional SQLite files are downloaded the first time a tool needs them (see Optional DB auto-download trigger).
5. Requirements: Node.js 18+ and the sqlite3 CLI on your PATH. The server runs queries via the SQLite command-line tool (not an embedded Node binding).

Databases

SQLite file	Default path	Download behavior	Includes
nds.sqlite	~/.nds-mcp/nds.sqlite	Auto-download on server startup (required)	AME2020 masses + reaction Q-values; NUBASE2020 nuclear properties; charge radii (IAEA + Li2021 laser spectroscopy); ENSDF (levels, gammas, decay feedings, references); TUNL light-nuclei resonance/level data (A=4–20); CODATA fundamental constants
jendl5.sqlite (optional)	~/.nds-mcp/jendl5.sqlite	Auto-download on first call to JENDL-5 tools	JENDL-5 decay data + radiation spectra; JENDL-5 pointwise cross sections + ENDF-6 interpolation laws
exfor.sqlite (optional)	~/.nds-mcp/exfor.sqlite	Auto-download on first call to EXFOR tools	EXFOR experimental data points (SIG/MACS/...) + per-entry metadata
fendl32c.sqlite (optional, maintainer ingest)	~/.nds-mcp/fendl32c.sqlite	Built via nds-mcp ingest --fendl (status visible in nds_info)	FENDL-3.2c evaluated ENDF-6 data for transport applications (photo-atomic, neutron, proton, deuteron) + embedded upstream zip archives (raw ENDF retained for MF/MT beyond what is normalized into tables)
irdff2.sqlite (optional, maintainer ingest)	~/.nds-mcp/irdff2.sqlite	Built via nds-mcp ingest --irdff (status visible in nds_info)	IRDFF-II evaluated ENDF-6 dosimetry neutron data + embedded upstream zip archives (raw ENDF retained for MF/MT beyond what is normalized into tables)

You can always bring your own files by setting NDS_DB_PATH / NDS_JENDL5_DB_PATH / NDS_EXFOR_DB_PATH / NDS_FENDL_DB_PATH / NDS_IRDFF_DB_PATH.

Glossary (Acronyms & Jargon)

• MCP: Model Context Protocol (the tool interface used by agents/LLMs).
• IAEA: International Atomic Energy Agency (many upstream nuclear-data sources and portals).
• AME2020: Atomic Mass Evaluation 2020 (atomic masses, separation energies, Q-values).
• NUBASE2020: Nuclear properties/decay evaluation (half-lives, spins, decay modes, isomers).
• ENSDF: Evaluated Nuclear Structure Data File (levels, gamma transitions, decay feedings).
• TUNL: Triangle Universities Nuclear Laboratory (light nuclei level/resonance tables, A=4–20).
• JENDL-5: Japanese Evaluated Nuclear Data Library v5 (evaluated nuclear data).
• EXFOR: Experimental Nuclear Reaction Data (experimental points + metadata).
• FENDL-3.2c: Fusion Evaluated Nuclear Data Library (transport-focused evaluated ENDF-6 sets).
• IRDFF-II: International Reactor Dosimetry and Fusion File (dosimetry-focused evaluated ENDF-6 sets).
• CODATA: Recommended fundamental constants (Committee on Data for Science and Technology).
• ENDF-6: Evaluated Nuclear Data File format (plain-text evaluated nuclear data, organized into sections).
• MAT / MF / MT: ENDF section identifiers: MAT (material id), MF (“file number”, data category), MT (reaction/quantity id). Example: MF=3 = pointwise cross sections; MT=1 = total; MT=2 = elastic; MT=102 = (n,γ) capture.
• XS: cross section.
• BLOB: SQLite “binary large object” column storing raw bytes. This project embeds some upstream zip archives as BLOBs for completeness; nds_query never returns BLOBs and forbids selecting them.
• SIG / MACS: EXFOR quantity codes: SIG = cross section; MACS = Maxwellian-averaged cross section.

Optional DB auto-download trigger

• jendl5.sqlite is downloaded when calling nds_get_radiation_spectrum, nds_list_available_targets, nds_get_reaction_info, nds_get_cross_section_table, or nds_interpolate_cross_section.
• exfor.sqlite is downloaded when calling nds_search_exfor or nds_get_exfor_entry.
• These optional SQLite assets are published on this repo's GitHub Releases page (latest release assets).
• Download URL can point to either plain .sqlite or compressed .sqlite.gz; server auto-gunzips when needed.
• For maintainers, jendl5.sqlite should include both decay tables and XS tables (jendl5_xs_meta / jendl5_xs_points / jendl5_xs_interp) before release upload.

Install (Optional)

Global install (lets you use command: "nds-mcp" in configs):

npm install -g nds-mcp
nds-mcp

From source:

git clone https://github.com/fkguo/nds-mcp.git
cd nds-mcp
pnpm install
pnpm build
node dist/index.js

Configuration

This is a local stdio MCP server. Launch options:

• npx (no install): command: "npx", args: ["-y", "nds-mcp"]
• global install: command: "nds-mcp", args: []

Clients using mcpServers (same JSON)

Claude Code (./.mcp.json), Cursor (./.cursor/mcp.json or ~/.cursor/mcp.json), Cline (cline_mcp_settings.json), Kimi Code CLI (~/.kimi/mcp.json), Qwen Code CLI (./.qwen/settings.json or ~/.qwen/settings.json).

{
  "mcpServers": {
    "nds-mcp": {
      "command": "npx",
      "args": ["-y", "nds-mcp"],
      "env": {}
    }
  }
}

VS Code (Copilot)

VS Code uses .vscode/mcp.json and a servers key:

{
  "servers": {
    "nds-mcp": {
      "command": "npx",
      "args": ["-y", "nds-mcp"]
    }
  }
}

Codex CLI

Add to ~/.codex/config.toml:

[mcp_servers.nds-mcp]
command = "npx"
args = ["-y", "nds-mcp"]

OpenCode

Add to opencode.json (project) or ~/.config/opencode/opencode.json (global):

{
  "mcp": {
    "nds-mcp": {
      "type": "local",
      "command": ["npx", "-y", "nds-mcp"],
      "enabled": true,
      "environment": {}
    }
  }
}

Cherry Studio

Settings → MCP Server → Add server:

• Type: STDIO
• Command: npx
• Parameters: -y nds-mcp

Generic stdio (manual)

npx -y nds-mcp

The server communicates over stdin/stdout (MCP protocol). Diagnostic messages go to stderr.

Data Sources

Source	Tables	Content
AME2020	ame_masses, ame_reactions	Mass excess, binding energy, separation energies, Q-values
NUBASE2020	nubase	Half-life, spin/parity, decay modes, isomers
IAEA (Angeli & Marinova 2013)	charge_radii	RMS charge radii
Li et al. 2021	laser_radii, laser_radii_refs	Laser spectroscopy charge radii with per-isotope references
ENSDF	ensdf_levels, ensdf_gammas, ensdf_decay_feedings, ensdf_datasets, ensdf_references	Nuclear structure: levels, gamma transitions, decay feedings
TUNL	tunl_levels	Light nuclei (A=4–20) energy levels, resonance widths, isospin, decay modes (59 nuclides, 2512 levels)
JENDL-5 Decay (optional, jendl5.sqlite)	jendl5_decays, jendl5_decay_modes, jendl5_radiation	Decay data + radiation spectra
JENDL-5 XS (optional, jendl5.sqlite)	jendl5_xs_meta, jendl5_xs_points, jendl5_xs_interp	Pointwise cross sections + ENDF-6 interpolation laws
EXFOR (optional, exfor.sqlite)	exfor_entries, exfor_points	Experimental data points (SIG/MACS/...)
CODATA 2022	codata_constants, codata_meta	Fundamental constants (value/uncertainty/unit, exact/truncated flags)

Masses, Thresholds, and Near-Threshold Resonances (Important)

• nds_get_mass returns AME atomic masses (neutral atoms; electrons included). This is standard: many Q-values/threshold computations can be done directly with atomic masses because electron masses largely cancel for reactions with the same total Z.
• If you need nuclear masses, convert via M_nuc = M_atom - Z*m_e + B_e/c^2 (electron binding energies B_e are eV-scale for light nuclei; include them only if you need sub-keV precision).
• For unbound nuclei / broad resonances (e.g. 5He, 5Li), a single real-number “ground-state energy/mass” depends on the resonance-parameter convention (S-matrix pole vs eigenphase centroid vs cross-section peak). Mixing AME masses with level energies from ENSDF/TUNL/evaluations can yield O(10–100 keV) shifts and even “threshold-above vs threshold-below” sign flips. When doing threshold comparisons for such systems, use a single self-consistent evaluation/convention.

Tools

Tool	Description
nds_info	Database metadata: data versions, nuclide counts, file hash, optional DB status, and build/source metadata
nds_catalog	Catalog installed libraries and query entrypoints (what exists, where to query, and which tools to use)
nds_schema	Inspect SQLite schema for an installed library (tables/columns/foreign keys; indexes optional)
nds_query	Safe structured table query builder (filter/sort/paginate; no raw SQL). Enforces BLOB exclusion + *_points guardrails
nds_list_raw_archives	List embedded upstream ENDF-6 zip archive metadata for FENDL/IRDFF (never returns BLOB payloads)
nds_check_update	Check npm registry for newer nds-mcp version (read-only; no update performed)
nds_find_nuclide	Find nuclides by element, Z, and/or A (NUBASE2020)
nds_get_mass	Atomic mass data: mass excess, binding energy/A, atomic mass (AME2020)
nds_get_separation_energy	Nucleon separation energies: Sn, Sp, S2n, S2p (AME2020)
nds_get_q_value	Reaction Q-values: Qa, Q2bm, Qep, Qbn, etc. (AME2020)
nds_get_decay	Decay info: half-life, spin/parity, decay modes (NUBASE2020)
nds_get_charge_radius	Nuclear charge radii with cross-source comparison (`mode=best
nds_search	Search nuclides by property range (half-life, mass excess)
nds_query_levels	Nuclear energy levels from ENSDF + TUNL (auto-merged for A ≤ 20, with source discriminator)
nds_query_gammas	Gamma-ray transitions from ENSDF
nds_query_decay_feedings	Beta/EC decay feeding patterns from ENSDF
nds_lookup_reference	ENSDF/NSR bibliographic references
nds_get_radiation_spectrum	JENDL-5 decay radiation spectra (discrete lines + continuous summaries)
nds_list_available_targets	List available JENDL-5 XS targets (A/state) for a given Z/projectile
nds_get_reaction_info	List available JENDL-5 reaction channels for one target (mt/reaction/e-range/point-count)
nds_get_cross_section_table	JENDL-5 cross-section tables (`mode=raw
nds_interpolate_cross_section	ENDF-6 NBT/INT interpolation at one incident energy
nds_search_exfor	Search EXFOR data points (supports `quantity=SIG
nds_get_exfor_entry	Load full EXFOR entry payload by entry_id
nds_get_constant	Get one CODATA fundamental constant by name
nds_list_constants	List CODATA constants with filter and pagination

Universal Query (Schema + Structured Queries)

Use nds_schema to discover tables/columns, then nds_query to query them safely.

Safety rules enforced by nds_query:

• BLOB columns are never returned and cannot be explicitly selected (e.g. raw archive content fields).
• For big *_points tables, you must include a high-selectivity equality filter:
  • where.eq.xs_id (evaluated XS tables), or
  • where.eq.entry_id (EXFOR points)
• For embedded raw archives tables, you can query metadata columns (e.g. rel_path, sha256, size_bytes) but not the BLOB payload itself.
  • For convenience, use nds_list_raw_archives to list raw-archive metadata (FENDL/IRDFF) without dealing with table names.

Cross-Source Rule

For the same physical observable that exists in multiple sources/databases, tools return source-tagged values from each source by default. Any recommended / best value is an additional field and does not replace or hide other source values.

Example: Charge Radii (new source-tagged output)

Use mode=compare to get all source-tagged values plus an explicit comparison summary:

[
  {
    "Z": 4,
    "A": 10,
    "mode": "compare",
    "source_values": [
      {
        "source_name": "Li et al. laser spectroscopy",
        "value_fm": 2.355,
        "uncertainty_fm": 0.017,
        "unit": "fm"
      },
      {
        "source_name": "IAEA charge radii",
        "value_fm": 2.355,
        "uncertainty_fm": 0.017,
        "unit": "fm"
      }
    ],
    "recommended_source": "Li et al. laser spectroscopy",
    "recommended_r_charge_fm": 2.355,
    "recommended_r_charge_unc_fm": 0.017,
    "max_source_diff_fm": 0
  }
]

This reflects the current cross-source contract: return source-tagged values by default, and keep recommended/best as an additional field.

Example: JENDL-5 Pb-208 n,gamma

Raw points table:

{
  "tool": "nds_get_cross_section_table",
  "args": {
    "Z": 82,
    "A": 208,
    "projectile": "n",
    "mt": 102,
    "mode": "raw",
    "limit": 20
  }
}

Single-energy interpolation:

{
  "tool": "nds_interpolate_cross_section",
  "args": {
    "Z": 82,
    "A": 208,
    "projectile": "n",
    "mt": 102,
    "energy_eV": 0.0253
  }
}

Optional clamped interpolation (instead of out-of-range error):

{
  "tool": "nds_interpolate_cross_section",
  "args": {
    "Z": 82,
    "A": 208,
    "projectile": "n",
    "mt": 102,
    "energy_eV": 1000000000000,
    "on_out_of_range": "clamp"
  }
}

Reaction channel discovery for one target:

{
  "tool": "nds_get_reaction_info",
  "args": {
    "Z": 82,
    "A": 208,
    "state": 0,
    "projectile": "n"
  }
}

If requested mt/reaction is absent for the nuclide, the server returns INVALID_PARAMS with available_mts and available_reactions. If Z exists but requested A/state has no XS rows, server returns INVALID_PARAMS with available_targets (instead of generic not-found). For common naming confusion (e.g., Li-6 n,a vs ENDF/JENDL n,t MT=105), error payload may include suggested_reaction. nds_interpolate_cross_section defaults to on_out_of_range="error" (current behavior). With on_out_of_range="clamp", response includes clamped, requested_energy_eV, effective_energy_eV, tabulated_e_min_eV, and tabulated_e_max_eV. For nds_search_exfor INVALID_PARAMS, payload includes structured guidance: parameter dependency/mutual-exclusion rules, copyable example calls, and available_for_Z overview (projectiles/quantities/A_values) when available. Cross-section responses include explicit context fields: energy_unit="eV", cross_section_unit="b", jendl5_xs_version. Cross-section responses also include both mt (ENDF MT number) and a human-meaningful reaction label plus reaction_description so users/agents don't need to memorize MT codes.

Environment Variables

Variable	Default	Description
NDS_TOOL_MODE	standard	Tool exposure: standard (default) or full. full additionally exposes nds_self_update (npm self-update; requires explicit confirm in tool args). Restart MCP clients after updating the package.
NDS_DB_PATH	~/.nds-mcp/nds.sqlite	Database path. Set to skip auto-download.
NDS_JENDL5_DB_PATH	~/.nds-mcp/jendl5.sqlite	Optional JENDL-5 database path (auto-downloaded on first use if unset).
NDS_JENDL5_DB_DOWNLOAD_URL	GitHub Releases latest	Override auto-download URL for jendl5.sqlite.
NDS_EXFOR_DB_PATH	~/.nds-mcp/exfor.sqlite	Optional EXFOR database path (auto-downloaded on first use if unset).
NDS_EXFOR_DB_DOWNLOAD_URL	GitHub Releases latest	Override auto-download URL for exfor.sqlite.
NDS_FENDL_DB_PATH	~/.nds-mcp/fendl32c.sqlite	Optional FENDL-3.2c DB path (maintainer ingest / status in nds_info).
NDS_FENDL_DB_DOWNLOAD_URL	GitHub Releases latest	Override auto-download URL for fendl32c.sqlite.
NDS_IRDFF_DB_PATH	~/.nds-mcp/irdff2.sqlite	Optional IRDFF-II DB path (maintainer ingest / status in nds_info).
NDS_IRDFF_DB_DOWNLOAD_URL	GitHub Releases latest	Override auto-download URL for irdff2.sqlite.
NDS_DB_DOWNLOAD_URL	GitHub Releases latest	Custom download URL for the SQLite file.

Building the Database from Source

Maintainer-only: MCP clients never call these commands.

See RUNBOOK.md (repo only) for full SOP and raw input requirements. Minimal JENDL-5 build:

# Decay sublibrary
scripts/download-jendl5-dec.sh ~/.nds-mcp/raw/jendl5-dec_upd5.tar.gz
pnpm run ingest:jendl5-dec -- --source ~/.nds-mcp/raw/jendl5-dec_upd5.tar.gz --output ~/.nds-mcp/jendl5.sqlite

# Neutron pointwise XS sublibrary (300K, full archive)
scripts/download-jendl5-xs.sh ~/.nds-mcp/raw/jendl5-n-300K.tar.gz
pnpm run ingest:jendl5-xs -- --source ~/.nds-mcp/raw/jendl5-n-300K.tar.gz --output ~/.nds-mcp/jendl5.sqlite

--jendl5-xs accepts tar/tgz/zip archives, extracted directories, single ENDF text files (.dat / .endf / .txt, including .gz), and json/jsonl sources. Zip extraction uses system unzip; install it on hosts that run ingest jobs.

Release upload flow for optional DBs:

scripts/check-db.sh --only main,jendl5
scripts/release-phase2-dbs.sh --tag <tag> --repo fkguo/nds-mcp --jendl5 ~/.nds-mcp/jendl5.sqlite

Rule: build sqlite first, verify it locally, then upload release asset.

License

MIT