mcp-molecules

# mcp-molecules [](https://github.com/laszlopere/mcp-molecules/actions/workflows/ci.yml) [](https://pypi.org/project/mcp-molecules/) [](https://www.python.org/) [](LICENSE) [](https://github.com/sponsors/laszlopere) [](https://github.com/astral-sh/ruff) [](https://mypy-lang.org/) [](https://github.com/laszlopere/mcp-molecules/commits) **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). ## 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. - **`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. ## Install ```sh uv tool install mcp-molecules ``` ## Register with Claude Code ```sh claude mcp add molecules -- mcp-molecules ``` ## Development ```sh 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: ```sh 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](https://github.com/sponsors/laszlopere). ## 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](LICENSE). The bundled NIST data is public domain.