Summary
Wraps the PubChem REST APIs to let Claude search chemical compounds, pull properties, safety data, bioactivity profiles, and cross-references without leaving the conversation. You get 10 tools covering identifier lookup (name, SMILES, InChIKey), substructure and similarity searches, GHS hazard classification, drug interaction data, and BioAssay queries. Results include molecular descriptors, 2D/3D structures, pharmacological classifications, and links to external databases like DrugBank and ChEMBL. Ships with both stdio and a public HTTP endpoint at pubchem.caseyjhand.com, so you can skip the local install. Built on the author's mcp-ts-core framework with rate limiting and retry logic baked in. Useful for chemistry research, drug discovery workflows, or any task that needs programmatic access to one of the largest open chemical databases.
Install to Claude Code
verifiedclaude mcp add --transport http pubchem https://pubchem.caseyjhand.com/mcpRun in your terminal. Add --scope user to make it available in every project.
Review the command, arguments, and environment values before installing — MCP servers run with your local permissions.
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →
Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →
Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →
On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →
Tools
Verified live against the running server on Jun 10, 2026.
verified live10 tools
pubchem_search_compoundsSearch PubChem for chemical compounds by identifier (name, SMILES, or InChIKey, batched up to 25), molecular formula in Hill notation, substructure or superstructure containment, or 2D Tanimoto similarity. Optionally hydrate results with properties to avoid a follow-up pubchem...10 params
Search PubChem for chemical compounds by identifier (name, SMILES, or InChIKey, batched up to 25), molecular formula in Hill notation, substructure or superstructure containment, or 2D Tanimoto similarity. Optionally hydrate results with properties to avoid a follow-up pubchem...
Parameters* required
querystringRequired for substructure/superstructure/similarity searches. A SMILES string (e.g. "CC(=O)O") or PubChem CID as a string (e.g. "2244").
formulastringRequired for formula search. Molecular formula in Hill notation (e.g. "C6H12O6", "CaH2O2").
queryTypestringRequired for structure/similarity searches. Format of the query: "smiles" or "cid".one of
smiles · cidthresholdnumberSimilarity search only. Minimum Tanimoto similarity (70-100). 90+ for close analogs, 70-80 for scaffold hops. Default: 90.default: 90
maxResultsnumberMaximum CIDs to return (1-200). Default: 20.default: 20
propertiesarrayOptional: fetch these properties for each result, avoiding a follow-up details call. E.g. ["MolecularFormula", "MolecularWeight", "CanonicalSMILES"].
searchType*stringSearch strategy. "identifier": name/SMILES/InChIKey lookup. "formula": molecular formula. "substructure": find compounds containing the query as a substructure. "superstructure": find compounds that are themselves substructures of the query. "similarity": 2D Tanimoto similarity to the query.one of
identifier · formula · substructure · superstructure · similarityidentifiersarrayRequired for identifier search. Array of identifiers to resolve (1-25). Examples: ["aspirin", "ibuprofen"] for name, ["CC(=O)OC1=CC=CC=C1C(=O)O"] for SMILES, ["BSYNRYMUTXBXSQ-UHFFFAOYSA-N"] for inchikey (27-char block format).
identifierTypestringRequired for identifier search. Type of chemical identifier: "name", "smiles", or "inchikey".one of
name · smiles · inchikeyallowOtherElementsbooleanFormula search only. When true, includes compounds with additional elements beyond the formula.default: false
pubchem_get_compound_detailsGet detailed compound information by CID. Returns physicochemical properties (molecular weight, SMILES, InChIKey, XLogP, TPSA, etc.), optionally with a textual description (pharmacology, mechanism, therapeutic use), all known synonyms, drug-likeness assessment (Lipinski/Veber...7 params
Get detailed compound information by CID. Returns physicochemical properties (molecular weight, SMILES, InChIKey, XLogP, TPSA, etc.), optionally with a textual description (pharmacology, mechanism, therapeutic use), all known synonyms, drug-likeness assessment (Lipinski/Veber...
Parameters* required
cids*arrayPubChem Compound IDs to fetch (1-100). Batched efficiently. Resolve from names/SMILES with pubchem_search_compounds.
propertiesarrayProperties to retrieve. Defaults to a core set: MolecularFormula, MolecularWeight, IUPACName, CanonicalSMILES, IsomericSMILES, InChIKey, XLogP, TPSA, HBondDonorCount, HBondAcceptorCount, RotatableBondCount, HeavyAtomCount, Charge, Complexity.
includeSynonymsbooleanFetch all known names and synonyms (trade names, systematic names, registry numbers). One API call per CID — slower than the property batch for large CID lists.default: false
maxDescriptionsintegerMax number of distinct description entries per compound (1-20). PubChem returns near-duplicate summaries from many depositors; we dedup and cap to keep responses focused. Default: 3.default: 3
includeDescriptionbooleanInclude textual descriptions (pharmacology, mechanism, therapeutic use) attributed by source. Well-studied compounds have many overlapping summaries — capped via maxDescriptions. Fetched only for the first 10 CIDs in the batch; remaining CIDs return without descriptions.default: false
includeDrugLikenessbooleanCompute drug-likeness assessment: Lipinski Rule of Five (MW, XLogP, HBD, HBA) and Veber rules (TPSA, rotatable bonds). No extra API calls — computed from properties.default: false
includeClassificationbooleanInclude pharmacological classification: FDA Established Pharmacologic Classes, mechanisms of action, MeSH classes, and ATC codes. Fetched only for the first 10 CIDs in the batch; remaining CIDs return without classification.default: false
pubchem_get_compound_imageFetch a 2D structure diagram (PNG image) for a compound by CID.2 params
Fetch a 2D structure diagram (PNG image) for a compound by CID.
Parameters* required
cid*integerPubChem Compound ID. Resolve from name/SMILES with pubchem_search_compounds.
sizestringImage size: "small" (100x100) or "large" (300x300). Default: "large".one of
small · largedefault: largepubchem_get_compound_3d_structureGet a compound's default 3D conformer — atomic coordinates and bonds — for one CID. format="json" (default) returns parsed atoms and bonds the model can reason over directly; format="sdf" returns the raw V2000 SDF text for passthrough to docking, rendering, or conformer tools....3 params
Get a compound's default 3D conformer — atomic coordinates and bonds — for one CID. format="json" (default) returns parsed atoms and bonds the model can reason over directly; format="sdf" returns the raw V2000 SDF text for passthrough to docking, rendering, or conformer tools....
Parameters* required
cid*integerPubChem Compound ID. Resolve from name/SMILES with pubchem_search_compounds.
formatstringOutput format. "json" (default) returns parsed atoms and bonds. "sdf" returns the raw V2000 SDF text for passthrough to other tools.one of
sdf · jsondefault: jsonincludeAlternateConformerIdsbooleanList the IDs of additional computed conformers beyond the default. Adds one extra API call. Default: false.default: false
pubchem_get_compound_xrefsGet external database cross-references for a compound: PubMed citations, patent IDs, gene/protein associations, registry numbers, and taxonomy IDs. Results are capped per type with total counts reported.3 params
Get external database cross-references for a compound: PubMed citations, patent IDs, gene/protein associations, registry numbers, and taxonomy IDs. Results are capped per type with total counts reported.
Parameters* required
cid*integerPubChem Compound ID. Resolve from name/SMILES with pubchem_search_compounds.
xrefTypes*arrayCross-reference types to retrieve. String IDs: RegistryID (DSSTox/EPA registry numbers), RN (CAS numbers), PatentID. Numeric IDs: PubMedID, GeneID (NCBI Gene), ProteinGI (legacy NCBI Protein GI), TaxonomyID.
maxPerTypenumberMax IDs to return per xref type (1-500). A compound may have thousands of PubMed references. Total count always reported. Default: 50.default: 50
pubchem_get_compound_safetyGet GHS (Globally Harmonized System) hazard classification and safety data for one or more compounds by CID. Returns signal word, pictograms, hazard statements (H-codes), and precautionary statements (P-codes) per compound. Data sourced from PubChem depositors — source attribu...1 params
Get GHS (Globally Harmonized System) hazard classification and safety data for one or more compounds by CID. Returns signal word, pictograms, hazard statements (H-codes), and precautionary statements (P-codes) per compound. Data sourced from PubChem depositors — source attribu...
Parameters* required
cids*arrayPubChem Compound IDs to fetch safety data for (1-25). Resolve from names/SMILES with pubchem_search_compounds.
pubchem_get_bioactivityGet a compound's bioactivity profile: which assays tested it, activity outcomes (Active/Inactive/Inconclusive), target identifiers (NCBI Gene ID, UniProt/GenBank accession), and quantitative values (IC50, EC50, Ki, etc.). Filter by outcome and/or a specific molecular target (N...5 params
Get a compound's bioactivity profile: which assays tested it, activity outcomes (Active/Inactive/Inconclusive), target identifiers (NCBI Gene ID, UniProt/GenBank accession), and quantitative values (IC50, EC50, Ki, etc.). Filter by outcome and/or a specific molecular target (N...
Parameters* required
cid*integerPubChem Compound ID. Resolve from name/SMILES with pubchem_search_compounds.
maxResultsnumberMax assay results to return (1-100). Well-studied compounds have thousands of records. Default: 20.default: 20
targetGeneIdintegerFilter to assays against this NCBI Gene ID. Obtain Gene IDs from pubchem_search_assays or the targetGeneId field of an unfiltered result here. Combine with outcomeFilter="active" to answer "is this compound active against target T?".
outcomeFilterstringFilter by activity outcome. "active" shows only assays where the compound showed activity — most useful for understanding biological profile. Default: "all".one of
active · inactive · alldefault: alltargetAccessionstringFilter to assays against this target protein accession (UniProt/GenBank), e.g. "P35354". Obtain accessions from pubchem_search_assays or the targetAccession field of an unfiltered result here.
pubchem_get_compound_interactionsGet a compound's interaction data: drug-drug interactions (DrugBank), drug-food interactions, and chemical-target interactions (binding/activity from BindingDB, ChEMBL, and others). Each entry carries its originating source. Richest for approved drugs; many compounds have no d...3 params
Get a compound's interaction data: drug-drug interactions (DrugBank), drug-food interactions, and chemical-target interactions (binding/activity from BindingDB, ChEMBL, and others). Each entry carries its originating source. Richest for approved drugs; many compounds have no d...
Parameters* required
cid*integerPubChem Compound ID. Resolve from name/SMILES with pubchem_search_compounds.
kindsarrayInteraction kinds to fetch. "drug-drug" (interactions with other drugs), "drug-food" (dietary interactions), "target" (binding/activity against molecular targets). Default: ["drug-drug"].
maxEntriesintegerMax entries per kind (1-50). Well-studied drugs have a long tail of interactions. Default: 10.default: 10
pubchem_search_assaysFind PubChem bioassays associated with a biological target. Search by gene symbol (e.g. "EGFR"), protein name, NCBI Gene ID, or UniProt accession. Returns assay IDs (AIDs) which can be explored further with pubchem_get_summary.3 params
Find PubChem bioassays associated with a biological target. Search by gene symbol (e.g. "EGFR"), protein name, NCBI Gene ID, or UniProt accession. Returns assay IDs (AIDs) which can be explored further with pubchem_get_summary.
Parameters* required
maxResultsnumberMax AIDs to return (1-200). Popular targets may have thousands of assays. Default: 50.default: 50
targetType*stringTarget identifier type. "genesymbol" and "proteinname" accept text names. "geneid" accepts NCBI Gene IDs. "proteinaccession" accepts UniProt accessions.one of
genesymbol · proteinname · geneid · proteinaccessiontargetQuery*stringTarget identifier. Examples: "EGFR" (genesymbol), "Epidermal growth factor receptor" (proteinname), "1956" (geneid), "P00533" (proteinaccession).
pubchem_get_summaryGet descriptive summaries for PubChem entities by ID. Supports assays (AID), genes (Gene ID), proteins (UniProt accession), and taxonomy (Tax ID). Up to 10 per call.2 params
Get descriptive summaries for PubChem entities by ID. Supports assays (AID), genes (Gene ID), proteins (UniProt accession), and taxonomy (Tax ID). Up to 10 per call.
Parameters* required
entityType*stringEntity type. Determines ID format and returned fields.one of
assay · gene · protein · taxonomyidentifiers*arrayEntity identifiers (1-10). Type depends on entityType:
- assay: AID (number), e.g. [1000]
- gene: Gene ID (number), e.g. [1956]
- protein: UniProt accession (string), e.g. ["P00533"]
- taxonomy: Tax ID (number), e.g. [9606]
@cyanheads/pubchem-mcp-server
Search the PubChem chemical database for compounds, properties, safety data, bioactivity, cross-references, and entity summaries via MCP. STDIO or Streamable HTTP.
10 Tools • 6 Resources
Public Hosted Server: https://pubchem.caseyjhand.com/mcp
Tools
Ten tools for querying PubChem's chemical information database:
| Tool Name | 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. |
pubchem_search_compounds
Search PubChem for chemical compounds across five search modes.
- Identifier lookup — resolve compound names, SMILES, or InChIKeys to CIDs (batch up to 25)
- Formula search — find compounds by molecular formula in Hill notation
- Substructure/superstructure — find compounds containing or contained within a query structure
- 2D similarity — find structurally similar compounds by Tanimoto similarity (configurable threshold)
- Optionally hydrate results with properties to avoid a follow-up details call
pubchem_get_compound_details
Get detailed compound information by CID.
- Batches up to 100 CIDs in a single request
- 27 available properties: molecular weight, SMILES, InChIKey, XLogP, TPSA, complexity, stereo counts, and more
- Optionally includes textual descriptions (pharmacology, mechanism, therapeutic use) from PUG View
- Optionally includes all known synonyms (trade names, systematic names, registry numbers)
- Optionally computes drug-likeness assessment (Lipinski Rule of Five + Veber rules) from fetched properties
- Optionally fetches pharmacological classification (FDA classes, mechanisms of action, MeSH classes, ATC codes)
pubchem_get_bioactivity
Get a compound's bioactivity profile from PubChem BioAssay.
- Returns assay outcomes (Active/Inactive/Inconclusive), target info (protein accessions, NCBI Gene IDs), and quantitative values (IC50, EC50, Ki)
- Filter by outcome and/or a specific molecular target (NCBI Gene ID or protein accession)
- Caps at 100 results per request (well-studied compounds may have thousands)
pubchem_get_summary
Get descriptive summaries for four PubChem entity types.
- Assays (AID), genes (Gene ID), proteins (UniProt accession), taxonomy (Tax ID)
- Up to 10 entities per call
- Type-specific field extraction for clean, structured output
pubchem_get_compound_interactions
Get a compound's interaction data by CID.
- Drug-drug interactions (DrugBank), drug-food interactions, and chemical-target binding/activity (BindingDB, ChEMBL, and others)
- Select which interaction kinds to fetch and cap entries per kind
- Each entry carries its originating source — coverage is richest for approved drugs
pubchem_get_compound_3d_structure
Get a compound's default 3D conformer by CID.
format="json"returns parsed atoms (element + x/y/z) and bonds for direct reasoning;format="sdf"returns raw V2000 SDF for passthrough to docking or rendering- Optionally lists alternate conformer IDs
- Returns a typed not-found when PubChem has no computed 3D coordinates (large molecules, mixtures, some salts)
Resources
Compound and assay records are also exposed as URI-templated MCP resources, backed by the same client methods as the tools:
| URI Template | Returns |
|---|---|
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). |
Features
Built on @cyanheads/mcp-ts-core:
- Declarative tool definitions — single file per tool, framework handles registration and validation
- Unified error handling across all tools
- Pluggable auth (
none,jwt,oauth) - Swappable storage backends:
in-memory,filesystem,Supabase,Cloudflare KV/R2/D1 - Structured logging with optional OpenTelemetry tracing
- Runs locally (stdio/HTTP) or containerized via Docker
PubChem-specific:
- Rate-limited client for PUG REST and PUG View APIs (5 req/s with automatic queuing)
- Retry with exponential backoff on 5xx errors and network failures
- All tools are read-only and idempotent — no API keys required
Getting Started
Public Hosted Instance
A public instance is available at https://pubchem.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
{
"mcpServers": {
"pubchem-mcp-server": {
"type": "streamable-http",
"url": "https://pubchem.caseyjhand.com/mcp"
}
}
}
Self-Hosted / Local
Add to your MCP client config (e.g., claude_desktop_config.json):
{
"mcpServers": {
"pubchem-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/pubchem-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio"
}
}
}
}
Prerequisites
- Bun v1.3.0 or higher (or Node.js v24+)
Installation
- Clone the repository:
git clone https://github.com/cyanheads/pubchem-mcp-server.git
- Navigate into the directory:
cd pubchem-mcp-server
- Install dependencies:
bun install
Configuration
No API keys are required — PubChem's API is freely accessible.
| Variable | Description | Default |
|---|---|---|
MCP_TRANSPORT_TYPE | Transport: stdio or http. | stdio |
MCP_HTTP_PORT | Port for HTTP server. | 3010 |
MCP_HTTP_HOST | Host for HTTP server. | localhost |
MCP_AUTH_MODE | Auth mode: none, jwt, or oauth. | none |
MCP_LOG_LEVEL | Log level (RFC 5424). | info |
STORAGE_PROVIDER_TYPE | Storage backend. | in-memory |
OTEL_ENABLED | Enable OpenTelemetry. | false |
Running the Server
Local Development
-
Build and run:
bun run rebuild bun run start:stdio # or start:http -
Run checks and tests:
bun run devcheck # Lints, formats, type-checks bun run test # Runs test suite
Docker
docker build -t pubchem-mcp-server .
docker run -p 3010:3010 pubchem-mcp-server
Project Structure
| Directory | Purpose |
|---|---|
src/mcp-server/tools/definitions/ | Tool definitions (*.tool.ts). |
src/services/pubchem/ | PubChem API client with rate limiting and response parsing. |
scripts/ | Build, clean, devcheck, and tree generation scripts. |
Development Guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
- Handlers throw, framework catches — no
try/catchin tool logic - Use
ctx.logfor domain-specific logging - Register new tools in the
index.tsbarrel file
Contributing
Issues and pull requests are welcome. Run checks before submitting:
bun run devcheck
bun run test
License
Apache-2.0 — see LICENSE for details.
Featured
Keep your Mac awake while Claude Code and 40+ AI agents run. Sleeps when they're idle.
One time payment $9 →Integrate web data into your AI product. One API to scrape website & brand data.
Get API Key Now →Agent, run crypto. Access onchain data & trade routes via 1inch.
Install now →On Capafy, your Skill runs online 24/7 as an agent product, and you get paid every time someone uses it.
Start earning →Configuration
MCP_LOG_LEVELdefault: infoSets the minimum log level for output (e.g., 'debug', 'info', 'warn').
MCP_HTTP_HOSTdefault: 127.0.0.1The hostname for the HTTP server.
MCP_HTTP_PORTdefault: 3010The port to run the HTTP server on.
MCP_HTTP_ENDPOINT_PATHdefault: /mcpThe endpoint path for the MCP server.
MCP_AUTH_MODEdefault: noneAuthentication mode to use: 'none', 'jwt', or 'oauth'.
Categories
Registryactive
Package@cyanheads/pubchem-mcp-server
TransportSTDIO, HTTP
Tools verifiedJun 10, 2026
UpdatedJun 2, 2026
