mcp-molecules is a chemistry toolkit for artificial intelligence, emphasizing trustworthy, offline, deterministic computation, and supported by authoritative data sources (such as the NIST Atomic Weights and Isotopic Compositions database). It runs as an MCP server, allowing language models to obtain trustworthy answers through actual computation rather than relying on memory when answering chemistry questions.
Main capabilities
molecular_weight_calculator: Calculates molecular weight (molar mass) from a chemical formula. Parameters include: formula (element symbols, integer multipliers, arbitrarily nested parentheses, and isotope labels D and T, e.g. H2O, C6H12O6, Ca(OH)2, Fe2(SO4)3, ((CH3)2CH)2, D2O, Tc); unit (unit, default g/mol, optional kg/mol, Da, u, kDa); uncertainty (propagates in quadrature using the NIST standard uncertainty for each element, reporting value ± sigma); monoisotopic (uses the most abundant isotope of each element to obtain the mass spectrometry monoisotopic mass, rather than the standard atomic weight); composition (returns the mass percent composition of each element).
isotope_distribution: Calculates the natural isotope distribution pattern of a chemical formula, i.e. the peaks a mass spectrometer would see, giving the mass, m/z, and relative intensity of each peak, as well as the monoisotopic mass and average mass. Parameters include: formula (syntax same as the molecular weight calculator); charge (default 0 means neutral mass; a nonzero n reports the m/z of the [M+nH] / [M-nH] ion); threshold (discards peaks below this percentage of the base peak, default 0.1); limit (maximum number of peaks to return, ordered from highest to lowest intensity, default 10); grouping (unit, default, collapses to integer nominal mass; exact preserves each resolved isotopologue).
find_chemical_compound: Finds compounds by name or molecular formula. It first searches the built-in offline database (a PubChem subset) and a writable user cache, then (unless disabled) uses online fallbacks (PubChem, Wikidata, and EPA CompTox when an API key is set), and caches the retrieved results. Parameters include: query (a name such as aspirin, acetylsalicylic acid, or a molecular formula such as H2O, C9H8O4; molecular formulas are matched by the Hill system); by (default auto, guesses name or formula, falling back to the other direction on a miss; name or formula can fix the direction); limit (maximum number of compounds to return when searching by molecular formula; isomers share the same molecular formula, with preferred names first). Online fallback is enabled by default; setting MCP_MOLECULES_ONLINE to a falsey value (0 / false / no / off) makes queries fully offline. The EPA CompTox data source also requires a free CCTE API key in MCP_MOLECULES_EPA_API_KEY, otherwise that source is skipped.
info: Server availability / version / environment health check.
Example questions that can be queried include: How much does one mole of glucose weigh (resolves the name to C6H12O6 and calculates the molar mass); what fraction of the mass of Fe2(SO4)3 is iron (percent composition of each element); the molar mass of caffeine and its uncertainty (propagates NIST standard uncertainty); what the mass spectrum of chloroform looks like (natural chlorine isotope pattern, peaks such as M, M+2, M+4); the [M+H]⁺ m/z of caffeine (protonated ion mass); which compound has the molecular formula C9H8O4 (molecular formula to name, aspirin among its isomers); what are the isomers of C2H6O (one molecular formula corresponding to multiple names, such as ethanol and dimethyl ether).
Usage and configuration
Element masses come from the NIST Atomic Weights and Isotopic Compositions database (https://physics.nist.gov/cgi-bin/Compositions/stand_alone.pl），属公有领域，数据以 mcp_molecules/data/nist_atomic_weights.json is bundled in the package. It can be registered via Claude Code. The pre-commit hook in the repository's .githooks/ automatically formats and checks staged Python files and must be enabled once per clone. The project is licensed under GPL-3.0-or-later, and the bundled NIST data is in the public domain.
Use cases and limitations
Suitable for AI scenarios requiring trustworthy chemical calculations, such as molecular weight, uncertainty, isotope distribution, and compound name/molecular formula queries. Its advantage lies in offline, deterministic calculations based on authoritative data. In terms of limitations, more molecule-oriented tools are still planned; the online fallback is enabled by default, and must be explicitly disabled if fully offline operation is required; the EPA CompTox source requires an additional API key. The project encourages sponsorship to sustain development.
