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 (, , ).
Nuclear Data Services MCP server — offline SQLite-backed nuclear physics data queries
2026-11-16
ดาว
—
เครื่องมือ
—
อัปไทม์
—
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
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).
Ask questions in chat. The agent chooses MCP tools based on your request; you do not need to call tools manually.
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.
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).
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).
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).
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):
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).
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)
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:
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:
--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.