pubchem-mcp-server

<div align="center"> <h1>@cyanheads/pubchem-mcp-server</h1> <p><b>Search the PubChem chemical database for compounds, properties, safety data, bioactivity, cross-references, and entity summaries via MCP. STDIO or Streamable HTTP.</b> <div>10 Tools • 6 Resources</div> </p> </div> <div align="center">

</div> <div align="center">

</div> <div align="center">

Public Hosted Server: https://pubchem.caseyjhand.com/mcp

</div>

---

Overview

Chemical compound and bioassay data from PubChem's PUG REST and PUG View APIs. Search compounds by identifier, formula, or structure; fetch physicochemical properties, safety data, bioactivity, interactions, cross-references, and 3D structures; find bioassays by biological target. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

| Tool | Description | |:---|:---| | pubchem_search_compounds | Search for compounds by name, SMILES, InChIKey, formula, substructure, superstructure, or 2D similarity. | | pubchem_get_compound_details | Get physicochemical properties, descriptions, synonyms, drug-likeness, and classification for compounds by CID. | | pubchem_get_compound_image | Fetch a 2D structure diagram (PNG) for a compound by CID. | | pubchem_get_compound_3d_structure | Fetch a 3D conformer (atomic coordinates and bonds) for a compound by CID, as parsed JSON or raw SDF. | | pubchem_get_compound_xrefs | Get external database cross-references (PubMed, patents, genes, proteins, etc.). | | pubchem_get_compound_safety | Get GHS hazard classification and safety data for one or more compounds by CID (batch). | | pubchem_get_bioactivity | Get a compound's bioactivity profile: assay results, targets, and activity values; filter by outcome or molecular target. | | pubchem_get_compound_interactions | Get drug-drug, drug-food, and chemical-target interactions for a compound by CID. | | pubchem_search_assays | Find bioassays by biological target (gene symbol, protein, Gene ID, UniProt accession). | | pubchem_get_summary | Get summaries for PubChem entities: assays, genes, proteins, taxonomy. |

Resources

Compound and assay records are also exposed as URI-templated resources, backed by the same client methods as the tools; many MCP clients are tool-only and never surface resources.

| Resource | Description | |:---|:---| | pubchem://compound/{cid} | Core physicochemical properties (JSON). | | pubchem://compound/{cid}/safety | GHS hazard classification (JSON). | | pubchem://compound/{cid}/image | 2D structure diagram (PNG). | | pubchem://compound/{cid}/xrefs | External cross-references (JSON). | | pubchem://compound/{cid}/bioactivity | Bioassay activity profile (JSON). | | pubchem://assay/{aid} | BioAssay summary (JSON). |

Capability reference

pubchem_search_compounds _tool

• Five search strategies: identifier (name/SMILES/InChIKey, batched 1-25), formula (Hill notation, optional allowOtherElements), substructure/superstructure containment, or 2D Tanimoto similarity (threshold 70-100, default 90)
• Each strategy needs its own fields — identifier: identifierType + identifiers; formula: formula; substructure/superstructure/similarity: query + queryType — and a missing or blank one is rejected before the upstream call
• Caps at 200 CIDs per page (default 20); offset pages to a ceiling of 10,000 — identifier lookups resolve every match up front so paging is free, while formula/structure/similarity searches cost more upstream per deep page
• Optional properties hydration avoids a follow-up pubchem_get_compound_details call
• Identifier mode reports unresolvedIdentifiers for inputs that resolved to no CID — no PubChem match, or a SMILES PubChem cannot interpret — while the rest of the batch still resolves, plus notices when multiple inputs collide on one CID
• A query PubChem cannot search on (malformed SMILES or formula, a * wildcard atom, a CID with no record) fails fast with a search_query_rejected hint naming what to fix
• Reports an exact totalFound when the full match set was observed, or a totalFoundAtLeast floor when a bounded upstream search saturated

---

pubchem_get_compound_details _tool

• Up to 100 CIDs per call; 27 available properties, defaulting to a core set of 14 (formula, weight, IUPAC name, SMILES forms, InChIKey, XLogP, TPSA, H-bond/rotatable-bond counts, heavy atom count, charge, complexity)
• Optional textual descriptions, paged via descriptionOffset/maxDescriptions (default 3, up to 20) — fetched only for the first 10 CIDs in the batch, remaining CIDs listed in skippedCids
• Optional synonyms for every found CID, paged via synonymOffset/maxSynonyms (default 20, up to 100)
• Optional drug-likeness assessment (Lipinski Rule of Five + Veber rules), computed from the returned properties at no extra latency
• Optional pharmacological classification (FDA classes/mechanisms, MeSH classes, ATC codes) — same 10-CID fan-out cap as descriptions
• Per-CID found: false distinguishes a nonexistent CID from a real compound PubChem simply has no data for

---

pubchem_get_compound_image _tool

• Single CID; size is "small" (100x100) or "large" (300x300, default)
• Returns base64-encoded PNG plus width/height
• Typed cid_not_found error when PubChem has no record for the CID

---

pubchem_get_compound_3d_structure _tool

• Single CID; format="json" (default) returns parsed atoms (element + x/y/z) and bonds, format="sdf" returns the raw V2000 SDF text
• maxAtoms/maxBonds cap the JSON preview (default 200 each); atomCount/bondCount always report the full totals, with any capping disclosed via enrichment
• includeRawSdf bypasses the default 500-line cap on the raw SDF text
• Optional includeAlternateConformerIds lists conformer IDs beyond the default
• Typed no_3d_structure error when PubChem has no computed 3D coordinates (large molecules, mixtures, some salts)

---

pubchem_get_compound_xrefs _tool

• Single CID; one or more xrefTypes — string IDs (RegistryID, RN for CAS numbers, PatentID) and numeric IDs (PubMedID, GeneID, ProteinGI, TaxonomyID)
• Paged per type: maxPerType up to 500 (default 50), with the same offset applied across every requested type
• Each type reports its own totalAvailable and truncated flag
• Empty-result notice distinguishes "this compound has none of the requested types" from a possibly-mistyped CID

---

pubchem_get_compound_safety _tool

• Batch of 1-25 CIDs
• Returns GHS signal word, pictograms, hazard statements (H-codes), and precautionary statements (P-codes), with source attribution
• Per-CID status: ok, no_ghs_data (compound exists, no deposited classification), or cid_not_found (no PubChem record at all) — kept distinct so a bad CID never reads as "no hazards on file"
• Precautionary statements carry a decoded flag — false for codes needing label-specific fill text or outside the decoder table; the code itself is still authoritative

---

pubchem_get_bioactivity _tool

• Single CID; filter by outcomeFilter (active/inactive/all, default all) and/or targetGeneId/targetAccession
• Caps at 100 results per page (default 20); offset reaches the rest
• Reports totalAssays/activeCount/inactiveCount for the whole compound, plus filteredCount/returnedCount for the current page
• Notices distinguish "no bioactivity data at all" from "the filter excluded everything" from "offset past the end"

---

pubchem_get_compound_interactions _tool

• Single CID; one or more kinds — drug-drug (DrugBank), drug-food, target (binding/activity from BindingDB, ChEMBL, and others); default ["drug-drug"]
• maxEntries per kind per page (1-50, default 10); offset counts source records rather than returned entries, capped at 2,147,483,646
• Each kind pages independently — paging[] reports per-kind totalRecords/nextOffset/truncated; the top-level nextOffset is populated only when exactly one requested kind still has records left
• A kind that fails to retrieve is named in failedKinds without failing the kinds that succeeded

---

pubchem_search_assays _tool

• Search by targetType: genesymbol/proteinname (text), geneid (NCBI Gene ID), proteinaccession (UniProt)
• Caps at 200 AIDs per page (default 50); offset pages to the total found
• Rejects a blank targetQuery and a non-numeric geneid query before the upstream call
• Reports totalFound across all pages and distinguishes "no match" from "offset past the end"

---

pubchem_get_summary _tool

• entityType: assay (AID), gene (NCBI Gene ID), protein (UniProt accession), or taxonomy (Tax ID); up to 10 identifiers per call
• Per-identifier found flag; populated fields depend on entityType (taxonomy includes an ordered lineage, gene includes symbol/taxonomy)
• Notice reports how many identifiers were not found and which ID type entityType expects

---

pubchem://compound/{cid} _resource

• Core physicochemical properties (the same default 14-property set as pubchem_get_compound_details), as application/json
• Throws a typed not-found when the CID doesn't exist in PubChem
• Use pubchem_get_compound_details to select specific properties or add descriptions, synonyms, drug-likeness, and classification

---

pubchem://compound/{cid}/safety _resource

• GHS hazard classification as application/json
• status (ok/no_ghs_data/cid_not_found) is the only signal distinguishing a bad CID from a compound with no deposited classification — a resource read has no notice surface

---

pubchem://compound/{cid}/image _resource

• 2D structure diagram, 300x300 PNG, returned as a base64 blob
• Use pubchem_get_compound_image for the 100x100 size option

---

pubchem://compound/{cid}/xrefs _resource

• Fo