Falls back to Wikidata to look up chemical compounds by name or formula when the offline database does not contain the query.
Atoms and molecules for the artificial minds — trustworthy chemistry tools, computed for real and backed by authoritative data.
Atoms combine into molecules, and a language model asked about them should not have to recall facts from memory; it should compute answers it can trust. mcp-molecules is a growing toolbox for working with chemical elements and molecules — offline, deterministic, and backed by authoritative sources such as the NIST Atomic Weights and Isotopic Compositions database.
For example, it can already take a chemical formula and return its molecular weight: ask "what does C₆H₁₂O₆ weigh?" and it parses the formula, looks every element up in NIST data, and computes the molar mass rather than guessing it. More molecule-oriented tools are planned.
You can ask things like:
"What does a mole of glucose weigh?" — resolves the name to C₆H₁₂O₆ and computes the molar mass.
"How much of Fe₂(SO₄)₃'s mass is iron?" — per-element percent composition.
"What's the molar mass of caffeine, with uncertainty?" — propagates the NIST standard uncertainties.
"What does the mass spectrum of chloroform look like?" — the natural chlorine isotope pattern (the M, M+2, M+4 … peaks).
"What's the [M+H]⁺ m/z for caffeine?" — the protonated-ion mass.
"Which compound has the formula C₉H₈O₄?" — formula → name (aspirin, among its isomers).
"What are the isomers of C₂H₆O?" — one formula, several names (ethanol and dimethyl ether).
molecular_weight_calculator — (one example of what's here today)
compute the molecular weight (molar mass) of a chemical formula. Parameters:
formula — element symbols, integer multipliers, arbitrarily nested
parentheses, and the isotope labels D (deuterium) and T (tritium).
Examples: H2O, C6H12O6, Ca(OH)2, Fe2(SO4)3, ((CH3)2CH)2, D2O, Tc.
unit — g/mol (default), kg/mol, Da, u, or kDa.
uncertainty — propagate the per-element NIST standard uncertainties in
quadrature and report value ± sigma.
monoisotopic — use the most abundant isotope of each element
(mass-spectrometry monoisotopic mass) instead of the standard atomic weight.
composition — return the per-element percent composition by mass.
isotope_distribution — compute the natural isotopic pattern (the peaks a
mass spectrometer would see) for a formula, with each peak's mass, m/z, and
relative intensity, plus the monoisotopic and average masses. Parameters:
formula — same syntax as molecular_weight_calculator.
charge — 0 (default) reports neutral masses; a non-zero n reports m/z
for the [M+nH]/[M-nH] ion.
threshold — drop peaks below this percent of the base peak (default 0.1).
limit — maximum peaks to return, most intense first (default 10).
grouping — unit (default) collapses to nominal integer masses; exact
keeps every resolved isotopologue.
find_chemical_compound — look up a compound by name or molecular
formula. Searches a bundled offline database (a PubChem subset) and a writable
user cache first, then — unless disabled — an online fallback (PubChem,
Wikidata, and, when an API key is set, EPA CompTox), caching what it fetches.
Parameters:
query — a name (aspirin, acetylsalicylic acid) or a formula
(H2O, C9H8O4); formulae are matched in the Hill system.
by — auto (default) guesses name vs. formula and falls back to the
other direction on a miss; name or formula pin the direction.
limit — maximum compounds to return for a formula lookup (isomers share
a formula), preferred name first.
The online fallback is on by default; set MCP_MOLECULES_ONLINE to a falsy
value (0/false/no/off) to keep lookups fully offline. The EPA CompTox
source additionally needs a free CCTE API key in MCP_MOLECULES_EPA_API_KEY;
without it that source is skipped.
info — server availability / version / environment health check.
Related MCP server: ChemDraw Server
uv tool install mcp-moleculesclaude mcp add molecules -- mcp-moleculesuv sync --all-extras
uv run mcp-molecules # run the server over stdio
uv run pytest # tests
uv run ruff format . # format
uv run ruff check . # lint
uv run mypy # type-checkA pre-commit hook in .githooks/ auto-formats and lints staged Python files
so the CI format gate can't be missed. Enable it once per clone:
git config core.hooksPath .githooksElement masses come from the NIST Atomic Weights and Isotopic Compositions
database (https://physics.nist.gov/cgi-bin/Compositions/stand_alone.pl), which
is in the public domain. The data is bundled in the package as
mcp_molecules/data/nist_atomic_weights.json.
Sponsoring this project will keep it alive. If it is useful to you, please consider sponsoring.
The idea and the inspiration came from Mátyás Mayer. The idea was excellent, the inspiration priceless.
GPL-3.0-or-later. See LICENSE. The bundled NIST data is public domain.
Infer a chemical formula from elemental mass percentages (inverse analysis).
The inverse of percent composition: given each element's mass percent -- what
a combustion / CHN elemental analyzer reports -- recover the best-fit
empirical formula, and, when molar_mass is also known, the molecular
formula. Masses come from the bundled NIST standard atomic weights, so the
computation is offline and deterministic.
Assumes a 100 g sample, converts each percentage to relative moles via the
atomic weights, normalises to whole-number atom ratios (searching integer
multipliers up to max_multiplier), and reduces to the empirical formula.
Use balance to assign an unmeasured element (typically oxygen) the
remainder up to 100%.
Returns the resolved_percentages (including any balance element), the
empirical_formula and its weight, the molecular_formula (null
without a molar mass) with its molecular_multiplier, and a fit block
-- the predicted_percentages the returned formula actually implies, the
per-element residuals, and the rms_error / max_abs_error in
percentage points. Any data-quality warnings (percentages not summing to
100%, a poor fit, a molar mass far from a whole multiple) are listed.
Raises ValueError on an unknown element, a non-positive percentage, or
percentages leaving no remainder for the balance element.
Inputs: percentages (required), balance, molar_mass, max_multiplier.
Look up a chemical compound by name or molecular formula.
Searches the bundled name<->formula database (a PubChem subset) first, then
the writable user cache, then -- unless disabled -- the online fallback
(PubChem, Wikidata, and, when an API key is set, EPA CompTox). A name
resolves to its molecular formula(e); a formula resolves to the compound
name(s) sharing it (isomers), ordered with the preferred name first. The
direction is chosen by by. Returns the query, how it was interpreted
(interpreted_as), the normalized Hill-system canonicalization of the
query whenever it parses as a formula (e.g. 'O6C6H12' -> 'C6H12O6'; null
when it is not a parseable formula), the matches (each
{"name", "formula"}, the preferred result first), and the resolving
source / license.
Raises ValueError if nothing matches.
Inputs: query (required), by, limit.
Report mcp-molecules server availability, version, and environment information.
Inputs: no named parameters.
Compute the natural isotopic pattern (isotope distribution) of a formula.
Returns the set of isotopologue peaks a mass spectrometer would see: each
peak's neutral mass (and mz when charge is non-zero), its
intensity relative to the base peak, and its absolute abundance.
Also reports the monoisotopic_mass (most-abundant isotope of each
element) and the average_mass. Backed by the bundled NIST Atomic Weights
and Isotopic Compositions database -- offline and deterministic.
Peaks below threshold percent of the base peak are dropped; at most
limit are returned. grouping selects nominal-mass (unit) or
fully resolved (exact) peaks.
Raises ValueError for an unparseable formula or an unknown element.
Inputs: formula (required), limit, charge, grouping, +1 more.
Compute the molecular weight (molar mass) of a chemical formula.
Parses formula into an atom tally, looks up each element's mass in the
bundled NIST Atomic Weights and Isotopic Compositions database, and returns
the total weight in the requested unit. Every call reports all three
distinct mass flavors under masses so callers never conflate them or have
to re-ask:
nominal -- sum of the integer mass numbers of the most abundant
isotopes,
average -- the standard atomic weight (average molar mass),
monoisotopic -- the exact mass of the most abundant isotopes.
The monoisotopic flag selects which of these is mirrored at the top level
(weight / uncertainty / formatted) and named by primary.
Optionally propagates NIST uncertainties (uncertainty) and/or reports
percent composition by mass (composition).
Raises ValueError for an unparseable formula or an unknown element.
Inputs: formula (required), unit, composition, uncertainty, +1 more.
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
Scored across 5 tools
Each tool targets a clearly distinct task: compound lookup, molecular weight calculation, isotope distribution, inverse elemental analysis, and server info. Although molecular_weight_calculator and isotope_distribution both return mass-related values, their primary outputs and use cases are clearly separated by the descriptions.
All names use snake_case and are descriptive, but the pattern is not a uniform verb_noun: most are noun phrases (elemental_analysis, isotope_distribution, molecular_weight_calculator), one is verb-led (find_chemical_compound), and info is a bare meta name. The set remains readable and mostly predictable.
Five tools is well within the ideal 3–15 range for a focused chemistry server. Each tool serves a distinct, non-redundant function, so the count feels well-scoped rather than bloated or thin.
The surface covers lookup, molecular weight, isotope distribution, and inverse formula inference, which are the core formula-centric operations. Minor gaps remain, such as direct formula parsing, exact-mass-to-formula search, or batch calculations, but agents can work around these.
MCP server for study aids: element table, formula lookup and knowledge-point practice.
PubChem MCP — NIH chemistry compound database (no auth)
MCP server for Riveter's enrichment, scraping, and monitoring API
Science MCP — free science data APIs
