bbn-mcp-server

An MCP server that exposes science tools — Big Bang Nucleosynthesis, the particle physics of the universe's first three minutes — to any LLM agent. Built on the same pattern as spectra-mcp-server and gaia-mcp-server; the multi-agent client in multiagent-client-demo drives any of these servers unchanged.

The science

Between one second and a few minutes after the Big Bang, the expanding universe ran a nuclear reactor. Its output — the primordial abundances of helium-4, deuterium, helium-3 and lithium-7 — is still measurable today, and it depends on exactly three things an agent can turn:

• the baryon density Ω_b h² (how much ordinary matter exists),
• extra relativistic species ΔN_eff (any light particle beyond the three Standard Model neutrinos — dark radiation, sterile states, axions — speeds up the expansion and changes the yields),
• the neutron lifetime τ_n (which sets the neutron/proton ratio at weak freeze-out — and whose laboratory measurements currently disagree by ~10 s, the "bottle vs beam" puzzle).

The classic stories are all here: the abundances and the CMB agree on the baryon density of the universe (concordance), helium counts the light degrees of freedom at t ~ 1 s, and the lithium-7 panel shows a famous unsolved problem — the prediction is ~3× the observed Spite plateau.

All computations run on PRyMordial (Burns, Tait & Valli, EPJC 84 (2024) 86), the community Python code for precision BBN within and beyond the Standard Model. PRyMordial is GPL-3.0 and not on PyPI, so it is not vendored here — a setup script fetches a pinned copy into extern/ (gitignored).

Tools

tool	what it does
describe_bbn_inputs()	parameters, measured abundances, references, the classic questions — call it first
compute_abundances(omega_b_h2, delta_neff, tau_n_s)	one full 63-reaction run: N_eff, Yp, D/H, ³He/H, ⁷Li/H, each with its pull (σ) against observation
scan_baryon_density(output_dir, ...)	abundances vs Ω_b h² → CSV (the Schramm-plot calculation)
plot_abundance_curves(scan_file, output_dir)	Yp, D/H, ⁷Li/H vs Ω_b h² with observed bands + the CMB baryon density
scan_neff(output_dir, ...)	abundances vs ΔN_eff (each point re-solves the thermal history) → CSV
plot_neff_impact(scan_file, output_dir)	how dark radiation shifts Yp and D/H — BBN as a particle counter
scan_neutron_lifetime(output_dir, ...)	Yp and D/H vs τ_n → CSV
plot_neutron_lifetime_impact(scan_file, output_dir)	Yp(τ_n) against the observed helium band and the discrepant bottle/beam measurements
fit_baryon_density(scan_file, observables)	χ² fit: the BBN-preferred Ω_b h² ± 1σ, compared with Planck — the concordance test in one number

Predictions carry the nuclear-rate systematic (PRIMAT compilation, PRyMordial's default) in quadrature with the measurement errors — the d(p,γ)³He rate alone moves D/H by a few percent, which is a genuine, live discussion in the field, not a bug.

Two conventions worth copying into any science MCP server:

1. Every tool returns {status, files, message, metadata} (ArtifactResult).
2. Arrays move between tools as file paths, never through the agent's context window.

Install

conda create -n bbn-tutorial python=3.12 -y
conda activate bbn-tutorial
pip install -e ".[dev]"
python scripts/setup_prymordial.py   # fetches PRyMordial + precomputes tables (~1 min)
pytest

The setup script clones a pinned PRyMordial commit into extern/PRyMordial (override with the PRYM_DIR env var) and runs one Standard Model computation with the save flags on, so the thermal background and weak rates are cached — that makes parameter scans ~6× faster and lets the server run without write access to the checkout.

Already have the spectra-tutorial env from the other servers? You can reuse it: pip install numba numdifftools, run the setup script, then always launch this server (and pytest) from this repo's root directory — all tutorial servers export packages named tools and mcp_server, so don't pip install -e several of them into one env; running from the repo root makes the local packages win.

Run the server

python -m mcp_server --transport streamable-http --port 8003

Clients connect to http://127.0.0.1:8003/mcp. Port 8003 by convention, so this server can run alongside spectra (8000), gaia (8001) and lattice (8002). Stop with Ctrl+C.

To use this server from Claude Code, the Claude desktop app, Codex, Cursor, or any other MCP client, see docs/mcp-clients.md — a checked-in .mcp.json already wires it into Claude Code.

Questions to ask an agent

"Does the baryon density measured by Planck in the CMB correctly predict the deuterium abundance we observe in quasar spectra? Scan the baryon density, fit it from the abundances, and give me the verdict in sigma."

"If there were one extra neutrino species in the early universe, what would have happened to primordial helium, and is that allowed by the data?"

The first one becomes a genuine two-server question when this server is hosted next to a CMB-capable one (compute the damping tail there, the deuterium here).