Skip to main content
Glama

pubchem-mcp-server

by io.github.cyanheads

Search Compounds

pubchem_search_compounds
Read-onlyIdempotent

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. Returns a page of CIDs — reach matches past maxResults with offset. Optionally hydrate results with properties to avoid a follow-up pubchem_get_compound_details call.

Input Schema

TableJSON Schema
NameRequiredDescriptionDefault
queryNoRequired for substructure/superstructure/similarity searches. A SMILES string (e.g. "CC(=O)O") or PubChem CID as a string (e.g. "2244").
offsetNoZero-based index of the first CID to return. Pass the nextOffset from a previous call to read the following page. Identifier lookups resolve every match up front, so paging them is free; formula, substructure, superstructure, and similarity searches have to ask PubChem for offset + maxResults records to reach a page, so deep pages cost progressively more upstream — hence the 10000 ceiling. Default: 0.
formulaNoRequired for formula search. Molecular formula in Hill notation (e.g. "C6H12O6", "CaH2O2").
queryTypeNoRequired for structure/similarity searches. Format of the query: "smiles" or "cid".
thresholdNoSimilarity search only. Minimum Tanimoto similarity (70-100). 90+ for close analogs, 70-80 for scaffold hops. Default: 90.
maxResultsNoMaximum CIDs to return per page (1-200). Use offset to reach matches past this page. Default: 20.
propertiesNoOptional: fetch these properties for each result, avoiding a follow-up details call. E.g. ["MolecularFormula", "MolecularWeight", "CanonicalSMILES"].
searchTypeYesSearch 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.
identifiersNoRequired 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).
identifierTypeNoRequired for identifier search. Type of chemical identifier: "name", "smiles", or "inchikey".
allowOtherElementsNoFormula search only. When true, includes compounds with additional elements beyond the formula.

Output Schema

TableJSON Schema
NameRequiredDescriptionDefault
capNoThe maxResults cap that was applied.
errorNoPresent when the call failed. Absent on success.
shownNoCIDs returned on this page.
noticeNoRecovery guidance when no compounds matched, when the offset runs past the matches observed, when identifiers failed to resolve, or when further pages remain. Absent when this page is complete and every identifier resolved.
offsetNoZero-based index of the first CID returned.
resultsNoMatching compounds.
truncatedNoTrue when matching CIDs remain past this page.
nextOffsetNoOffset to pass on the next call to continue past this page. Omitted when no further matches remain.
searchTypeNoSearch strategy used: identifier, formula, substructure, superstructure, or similarity.
totalFoundNoExact number of matching CIDs across all pages. Omitted when a formula, substructure, superstructure, or similarity search saturated the records it requested — PubChem returns no match count for those, so totalFoundAtLeast reports a floor instead.
totalFoundAtLeastNoLower bound on matching CIDs, reported in place of totalFound when the exact count is unavailable. At least this many match, and the true total may be higher; page further with offset to observe more.
unresolvedIdentifiersNoIdentifier-mode only: input identifiers that resolved to no CID. Omitted when every identifier resolved and for non-identifier searches.

TDQS

A4.5/5.0
Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations already declare readOnlyHint, openWorldHint, and idempotentHint. The description adds meaningful behavioral detail beyond those hints: results come as pages of CIDs, offset reaches matches past maxResults, and properties hydration avoids a secondary call. No contradiction with the annotations exists.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three sentences with no filler: search modes first, then paging behavior, then hydration guidance. Every sentence earns its place and the most important scoping information is front-loaded.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a tool with 11 parameters and five search strategies, the description surveys all modes, batching, paging, and hydration. An output schema exists, so omitting detailed return-value documentation is acceptable; the combination of description, schema, and annotations is complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description coverage is 100%, so the schema carries the full parameter-level detail. The description still adds value by linking the properties parameter to avoiding a follow-up call, highlighting the 25-item batch limit, and naming Hill notation and 2D Tanimoto similarity to orient the agent.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description states a specific verb and resource ('Search PubChem for chemical compounds') and enumerates all search strategy variants: identifier, formula, substructure, superstructure, similarity. It clearly separates this from sibling tools like pubchem_get_compound_details and pubchem_search_assays.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description gives clear context: use this to find compounds by structural or identifier-based criteria, and use the properties option to avoid a follow-up pubchem_get_compound_details call. It does not explicitly state when not to use it or name alternatives like pubchem_search_assays.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All pubchem-mcp-server toolsInspect
Try in Browser
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.

TDQS

A4.3/5.0
Disambiguation4/5

Tools cleanly separate into search (compounds, assays) and retrieval (details, structure, image, safety, xrefs, bioactivity, interactions, summary). The only mild overlap is bioactivity versus interactions, but their descriptions clarify that one focuses on assay outcomes and the other on drug-drug/food/chemical-target records.

Naming Consistency5/5

All tools follow a consistent pubchem_<verb>_<object> pattern, with get_ for retrieval and search_ for discovery. Minor variations like pubchem_get_summary still fit the same convention clearly.

Tool Count5/5

Ten tools is well-scoped for a PubChem client: search entry points, compound detail retrieval, structural representations, safety data, interaction data, and cross-reference lookups. Each tool earns its place without redundancy.

Completeness5/5

The surface covers the core PubChem workflows: finding compounds and assays, retrieving compound properties and structures, and exploring bioactivity, safety, interactions, and cross-references. Search results feed directly into retrieval tools, and paging is provided where needed, leaving no obvious dead ends.

Resources