mcp-molecules 0.1.0

An MCP server for molecular weight / molar mass calculation from chemical formulae, backed by the NIST atomic weights database.

mcp-molecules

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.

What it gives you

• 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.
• find_chemical_compound — look up a compound by name or molecular formula against a bundled offline database (a PubChem subset). 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.
• info — server availability / version / environment health check.

Install

uv tool install mcp-molecules

Register with Claude Code

claude mcp add molecules -- mcp-molecules

Development

uv 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-check

A 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 .githooks

Data

Element 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

Sponsoring this project will keep it alive. If it is useful to you, please consider sponsoring.

Credits

The idea and the inspiration came from Mátyás Mayer. The idea was excellent, the inspiration priceless.

License

GPL-3.0-or-later. See LICENSE. The bundled NIST data is public domain.