Pubchem Mcp Server

---

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, or list the compounds a bioassay found active.
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

• Six search strategies: identifier (name/SMILES/InChIKey, 25 looked up per call, the rest returned in unprocessed), formula (Hill notation, optional allowOtherElements), substructure/superstructure containment, 2D Tanimoto similarity (threshold 70-100, default 90), or assay (the compounds a bioassay marked active, or with activeOnly: false every compound it tested)
• Each strategy needs its own fields — identifier: identifierType + identifiers; formula: formula; substructure/superstructure/similarity: query + queryType; assay: aid — and a missing or blank one is rejected before the upstream call
• Caps at 200 CIDs per page (default 20; a larger maxResults is served at 200 and reported in cappedInputs); offset pages to a ceiling of 10,000 — identifier lookups resolve every match up front so paging is free, assay searches fetch only the requested page, while formula/structure/similarity searches cost more upstream per deep page
• Assay mode reports the exact count of active (or tested) compounds as totalFound, answers an assay with no actives with an empty page and a notice, and fails a nonexistent AID as aid_not_found
• 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, with any past that returned in unprocessed for a follow-up 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, capped at 20 per page) — 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, capped at 100 per page)
• 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; each human ATC code carries its WHO name and levels 1-4 (anatomical group down to chemical subgroup)
• 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 capped at 500 (default 50), with the same offset applied across every requested type
• Each type reports its own totalAvailable and truncated flag
• PubMedID comes highest first, so page one holds the most recently assigned PMIDs; GeneID, ProteinGI, and TaxonomyID come numerically ascending; string IDs keep PubChem's order
• Empty-result notice distinguishes "this compound has none of the requested types" from a possibly-mistyped CID

---

pubchem_get_compound_safety _tool

• Batch of up to 25 CIDs per call; any past that are returned in unprocessed, in input order, for a follow-up call
• Returns GHS signal word, pictograms, hazard statements (H-codes), and precautionary statements (P-codes) merged across sources; the signal word is the most severe any source assigns
• classifications[] keeps each source's label whole — EU harmonised, the ECHA C&L aggregate, single-company ECHA notifications, NITE-CMC revisions — with its own signal word, pictograms, H-codes carrying ECHA notifier agreement ("37.7%"), and notification counts; source lists only the sources that deposited a classification
• Per-CID status: ok, not_classified (every deposited classification is an ECHA "Not Classified" verdict — notifiers found no GHS hazard), 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
• A target filter matches every identifier the compound's own assay table ties to it — Gene ID 5742, UniProt P23219 and RefSeq NP_542158 all reach the same COX-1 assays — so the answer doesn't depend on which identifier the caller holds; passing both matches either, and nothing when the table ties them to different targets. Accessions are uppercased before matching (a PDB chain ID is kept as given)
• An assay that tests several targets keeps each one's outcome and values apart: the record reports the target the filter matched (else the first), and lists the rest under otherTargets
• Caps at 100 results per page (default 20); offset reaches the rest
• Reports totalAssays/activeCount/inactiveCount for the whole compound (a multi-target assay counts by its first listed target), 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 (capped at 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
• drug-drug and target come from PubChem's SDQ service, which can refuse automated requests; a refusal (an HTML page, a non-SDQ answer) fails the kind instead of reading as zero records, and the notice says a retry will not help. Per-target activity is also available from pubchem_get_bioactivity. drug-food comes from PUG View

---

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
• A comma-joined string is split into one identifier per piece, trimmed; pieces past the first 10 are returned in unprocessed, in input order, for a follow-up call, and more than 1000 pieces in all fails the call as too_many_identifiers
• AIDs, Gene IDs, and Tax IDs must be positive integers ("01000" reads as 1000); any other piece gets an invalid: true row and is never sent to PubChem, and the call fails as invalid_identifier only when no piece is usable
• Per-identifier found flag; populated fields depend on entityType (taxonomy includes an ordered lineage, gene includes symbol/taxonomy, assay includes method, the first 25 targets with targetCount, tested/active compound counts, and lastDataChange)
• Notice names invalid identifiers and reports how many were not found and which ID type entityType expects; cappedInputs points at unprocessed when the cap was reached

---

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, including the per-source ghs.classifications and the contributor source list
• status (ok/not_classified/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

• Focused default set — RN (CAS), RegistryID, PubMedID — up to 25 IDs per type, as application/json; the PubMed IDs are the 25 highest (most recently assigned), highest first
• Use pubchem_get_compound_xrefs for the full set of xref types, a higher per-type cap, and offset paging

---

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

• Up to 25 assays as application/json, plus totalAssays/activeCount for the whole compound; a multi-target assay lists its further targets under otherTargets
• Use pubchem_get_bioactivity to filter by outcome or target, raise the cap, or page with offset

---

pubchem://assay/{aid} _resource

• BioAssay summary as application/json — name, description, source, protocol, substance counts
• Throws a typed not-found when the AID doesn't exist

Features

Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.

PubChem-specific:

• Covers PUG REST (search, properties, cross-references, bioactivity), PUG View (textual descriptions, GHS classification, pharmacological classification, drug-food interactions), and SDQ (drug-drug and target interactions) endpoints
• Rate-limited client (5 req/s) with automatic request queuing, and one retry on 5xx errors, network failures, attempt timeouts, and unreadable response bodies — after 1 s, or after the Retry-After PubChem sends when it is 30 s or less and fits the call's remaining time (a longer one fails at once)
• One 50 s budget per tool call or resource read covers every PubChem request it makes — queue waits, each attempt's headers and body, and retry backoffs — so a slow or hung upstream fails the call as Timeout before an MCP client's default 60 s request timeout
• A cancelled tool call or resource read stops its PubChem work — queued requests, in-flight fetches, response bodies still arriving, retry backoffs, and async-search polling — and fails with RequestCancelled
• Hand-rolled V2000 SDF parser for 3D conformer atoms and bonds; drug-likeness (Lipinski/Veber) computed from already-fetched properties, adding no extra latency
• All tools are read-only and idempotent — no API keys required, PubChem's API is freely accessible

Agent-friendly output:

• Discriminated output contracts — per-CID status (ok / not_classified / no_ghs_data / cid_not_found) and found flags let callers branch on data instead of matching an error string
• Graceful partial failure — batch tools return per-item results alongside unresolvedIdentifiers, skippedCids, and failedKinds rather than failing the whole call
• Response shaping — truncation disclosure (truncated, shown/cap, nextOffset) on every capped list; an ID batch or page size past its per-call cap is served up to the cap instead of rejected, with the clamp reported in cappedInputs and any unserved IDs in unprocessed; plus a totalFoundAtLeast floor in place of a count when an upstream search saturates
• Typed error reasons — validation and not-found failures declare a reason (e.g. cid_not_found, missing_identifier_args, invalid_cid_query) with actionable recovery text, not generic messages

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 the following to your MCP client configuration file.

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/pubchem-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Or with npx (no Bun required):

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/pubchem-mcp-server@latest"],
      "env": {
        "MCP_TRANSPORT_TYPE": "stdio"
      }
    }
  }
}

Or with Docker:

{
  "mcpServers": {
    "pubchem-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/pubchem-mcp-server:latest"]
    }
  }
}

For Streamable HTTP, set the transport and start the server:

MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http
# Server listens at http://localhost:3010/mcp

Prerequisites

• Bun v1.4.0 or higher (or Node.js v24+).
• No API keys required — PubChem's API is freely accessible.

Installation

1. Clone the repository:

git clone https://github.com/cyanheads/pubchem-mcp-server.git

2. Navigate into the directory:

cd pubchem-mcp-server

3. Install dependencies:

bun install

4. Configure environment (optional):

cp .env.example .env
# edit .env to override transport, session mode, storage, or logging defaults

Configuration

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.	127.0.0.1
MCP_SESSION_MODE	stateless, stateful, or auto. PubChem needs no multi-round-trip input, so the server declares stateless; the example and Docker set it to match.	stateless
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

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  bun run devcheck   # Lint, format, typecheck, security
  bun run test       # Vitest test suite
  bun run lint:mcp   # Validate MCP definitions against spec
  

Docker

docker build -t pubchem-mcp-server .
docker run --rm -p 3010:3010 pubchem-mcp-server

The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/pubchem-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.

Project structure

Directory	Purpose
src/index.ts	createApp() entry point — registers tools/resources and inits the PubChem client.
src/mcp-server/tools/definitions/	Tool definitions (*.tool.ts).
src/mcp-server/resources/definitions/	Resource definitions (*.resource.ts).
src/services/pubchem/	PubChem API client — rate limiting, retry, and response/SDF parsing.
scripts/	Build, clean, devcheck, and tree generation scripts.
tests/	Unit and integration tests.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging
• Wrap external API calls: validate the raw PubChem response → normalize to a domain type → return the output schema; never fabricate missing fields
• Register new tools and resources in the index.ts barrel files

Contributing

Issues are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.