io.github.MysterionRisePublished by GitHub account MysterionRisev2.2.1Updated Nov 5, 2026
Search PubChem by structure: a local similarity/substructure index, live PubChem data, RDKit tools
The publisher's own server: Finder Jobs
PubChem Finder gives an assistant small-molecule chemistry tools: PubChem lookups and live structure search, a local similarity/substructure index, and…
Desktop only via STDIO. STDIO servers start a local process, so they need the SourceWeft desktop host.
Follow the launch instructions in the repository.
Search PubChem by chemical structure from your terminal or from Claude. PubChem Finder builds a local fingerprint index of PubChem (all of it, or the slice you need) for exact similarity and substructure search with no rate limits, wraps PubChem's live services for names, safety data and bioassays, and adds RDKit chemistry: structure drawings, med-chem triage and descriptors. Local search works from the first question, on a built-in set of 1,932 FDA-approved drugs, until you build a PubChem index. It runs as a command-line tool, a Python library and an MCP server for Claude Desktop, Claude Code and other MCP clients.
[PyPI] [Python] [CI] [License: MIT]
Real searches over the first 444,794 compounds of PubChem, rendered from the index the project's real-data workflow builds: similarity hits for aspirin with the atoms that differ from it highlighted, then hits for an aryl sulfonamide SMARTS with the match highlighted. MP4 version.
Other PubChem tools, MCP servers and hosted connectors included, forward questions to PubChem's web API. That works for looking compounds up, but structure search through the API is rate-limited, times out on generic queries and returns unscored samples. PubChem Finder also keeps a local index:
No database server, no Docker: the index is a pair of files in your data directory.
Requires uv, which fetches Python and everything else on first run.
Claude Code:
or as a plugin, which also works in Cowork:
Claude Desktop (Settings, Developer, Edit Config, then restart Claude):
Then ask things like:
O=C1C(=Cc2ccccc2)SC(=S)N1"[Sulfonamide drugs with the aryl sulfonamide SMARTS match highlighted]
draw_molecules with highlight="smarts": eight sulfonamide drugs with the match for
[NX3][SX4](=O)(=O)c highlighted, as Claude shows it inline.
Local similarity and substructure search work from the first question: until you build
an index, they search a built-in demo set of 1,932 FDA-approved drugs (built in about a
second on first use) and say so. Build a PubChem index from the command line (below) and
the server switches to it, no restart needed. To use a non-default data directory, add
"env": {"PUBCHEM_FINDER_HOME": "/path"} to the Claude Desktop entry, or
--env PUBCHEM_FINDER_HOME=/path to claude mcp add.
Other MCP clients: the server speaks standard MCP over stdio, so any client that runs
local MCP servers (Cursor, VS Code, Windsurf, Zed, JetBrains IDEs, Codex CLI, LM Studio...)
can start it with the same command and arguments. It is listed in the
MCP registry as io.github.MysterionRise/pubchem-finder
for clients that install servers from there.
docs/clients.md
has the settings, a quick check, and setups people have tested; if you use one of those
clients, adding yours there is a good first contribution.
Over HTTP: pubchem-finder mcp --transport http serves the same tools at
http://127.0.0.1:8000/mcp (MCP streamable HTTP) for clients that connect to a URL
rather than start a process, and for one shared index on a team machine. For example,
claude mcp add --transport http pubchem-finder http://127.0.0.1:8000/mcp. The server has
no authentication or TLS of its own: read
Over HTTP
before binding it to anything but 127.0.0.1.
Prompts start a whole workflow by name. In Claude Code they are slash commands, such as
/pubchem-finder:compound_dossier aspirin; each argument is one word (a SMILES works, and
a list is comma-separated without spaces).
Resources are data a client can attach to a conversation: pubchem://compound/{cid} (a
PubChem compound record as JSON; in Claude Code, @pubchem-finder:pubchem://compound/2244)
and pubchem://index/status.
uvx runs the package without installing it; --python 3.14 keeps uv off Python 3.15
(see Troubleshooting). To install the command once:
uv tool install --python 3.14 pubchem-finder (or pip install pubchem-finder on Python
3.11 to 3.14). The examples below
assume it is installed. To try the development version, replace pubchem-finder with
--from git+https://github.com/MysterionRise/pubchem-finder pubchem-finder in any uvx
command.
Before any index is built, search and substructure use the built-in demo set: 1,932
FDA-approved drugs (PubChem's parent compounds of what it links to Drugs@FDA), built into
<data directory>/demo in about a second on first use, and the results say so
(search_scope: "demo" in JSON). index build --demo builds it ahead of time;
PUBCHEM_FINDER_DEMO=0 turns the fallback off. Once a PubChem or SDF index is built,
searches use it.
index build --limit N downloads the first N of PubChem's 359 SDF chunks (up to 500,000
CIDs each; the first is a 323 MB download) from NCBI over HTTPS, verifies each file's MD5,
fingerprints it, deletes the download and merges everything into one searchable index. Re-running is safe: finished
chunks are skipped, so an interrupted build resumes and a larger --limit extends an
existing index. --all indexes all of PubChem. The default fingerprint is ECFP4 (Morgan
radius 2, 1024 bits); --radius and --fp-size change it for a new index.
--sdf FILE (repeatable) indexes your own files, alongside PubChem's chunks or on their
own. Each file becomes a chunk named after it, so two files with the same name (two
vendors' library.sdf) are refused rather than merged; rename one. Running the command
again after a file changed rebuilds that file's chunk.
Substructure search is optional because it needs a second fingerprint database. It is
built from the SMILES already in the index, so index build --with-substructure adds it to
an existing index without downloading anything, and later builds keep it up to date
(--without-substructure removes it). Each compound's RDKit pattern fingerprint is
screened first, then candidates are matched atom by atom (stereo is ignored). Hits come
lowest CID first, which puts long-known compounds first; the search stops after --max
hits or --max-candidates checked compounds and says whether it saw every candidate.
The pubchem commands query PubChem's live services, with no index needed:
PubChem's similarity search uses its own fingerprint and does not report scores, so each
hit is scored here with ECFP4, the same fingerprint as the local index, and sorted by it.
Successful responses are cached for 7 days, so repeated questions cost nothing and stay
within PubChem's rate limits (pubchem-finder cache info | clear; PUBCHEM_FINDER_CACHE=0
turns the cache off).
Rows that fail in batch mode get an error column instead of stopping the run.
[Aspirin analogues, with the atoms each one adds to aspirin highlighted]
--highlight diff: each analogue is aligned to the core it shares with aspirin, and the
atoms it adds are highlighted.
[Similarity maps of four compounds against aspirin]
--highlight similarity_map: atoms that raise ECFP4 similarity to aspirin in green,
atoms that lower it in pink.
The first column comes from real runs of index build --limit 1: on a MacBook Pro, and
with --with-substructure in the project's
real-data workflow on a standard GitHub Actions Linux
runner, which then runs every command and MCP tool against the result. The full-PubChem column
scales those numbers to PubChem's roughly 120 million compounds and is an estimate.
The built-in demo index (1,932 FDA-approved drugs, with substructure search) builds in about a second on first use and takes 5.4 MB.
Query times on the first chunk (GitHub runner): the similarity scan takes about 3 ms in memory and 0.12 s on disk, and fetching names and SMILES for 40 hits brings a full call to about 60 ms; a 50-hit substructure search takes 35-50 ms in memory and 0.3 s on disk. The first query also loads the index, which takes well under a second at this size. Screening time grows roughly linearly with the size of the index.
The index is searched in memory when it fits comfortably in available RAM and from disk
otherwise; set PUBCHEM_FINDER_INDEX_MODE=memory|disk to force a mode. On a laptop, index
a subset with --limit rather than all of PubChem.
Data lives in the platform data directory (~/.local/share/pubchem-finder on Linux,
~/Library/Application Support/pubchem-finder on macOS, %LOCALAPPDATA%\pubchem-finder
on Windows). Override it with --home DIR or PUBCHEM_FINDER_HOME.
The CLI and MCP server are thin layers over pubchem_finder.service:
To give your own agent the tools instead, talk to the MCP server:
examples/mcp_client.py
does it with the plain MCP client in under 50 lines (uv run examples/mcp_client.py, no
API key). Examples for agent frameworks are welcome, see
#34.
PATH, so uvx may not be found. Use its full path as the command
(run which uvx, typically ~/.local/bin/uvx). The server's log is in Claude
Desktop's MCP logs.similarity_search or substructure_search (with
PUBCHEM_FINDER_DEMO=0): build one with
pubchem-finder index build --limit 1 --with-substructure. The message (and
index_status) gives the exact command to paste into a terminal: it runs the server's
version through uvx and names the data directory if the server uses another one.HTTPS_PROXY; all requests to PubChem and NCBI honour it.uvx uses uv's newest Python whatever the
package supports, which is why the commands here pass --python 3.14; keep it in any
command or client config you write yourself.pubchem-finder cache clear empties the response cache; deleting the
data directory removes the index too.The data comes from PubChem, the National Library of Medicine's open chemistry database. Please follow NCBI's policies and PubChem's guidance on citing, and cite PubChem when you use its data:
Kim S, et al. PubChem 2025 update. Nucleic Acids Research 2025;53(D1):D1516-D1525. doi:10.1093/nar/gkae1059
Annotations (safety, pharmacology, toxicity...) are deposited by other organisations;
each one names its source, and some carry their own license terms. The demo set comes from
Drugs@FDA (U.S. Food and Drug
Administration, public domain) via PubChem, with PubChem's structures; see
src/pubchem_finder/index/demo_data/fda_approved_drugs.json.
PubChem Finder is built on RDKit, FPSim2, DuckDB, Apache Arrow and the MCP Python SDK. To cite PubChem Finder itself, see CITATION.cff (GitHub's "Cite this repository" button).
Requires uv. Python 3.11 to 3.14 are supported; the
repository's .python-version makes uv sync use 3.12 even if pyenv or conda put an
older Python first on your PATH.
The animation at the top is drawn from a real index by scripts/demo_media.py
(collect runs the searches and times them, render writes the GIF and MP4); its
docstring has the exact commands, and the real-data workflow renders it on every run.
docs/media/demo-data.json holds the results behind the current animation, so
uv run python scripts/demo_media.py render docs/media/demo-data.json -o docs/media
redraws it without an index.
CI runs the tests on Linux, macOS and Windows, smoke-tests the built wheel on all three, and runs the live PubChem tests weekly. See CONTRIBUTING, ROADMAP and CHANGELOG.
This repository started in 2020 as an Indigo + Elasticsearch indexer for PubChem dumps;
that code is in the git history before commit 06619d9.
MIT. See LICENSE.
Source: README.md at commit 7e475ac
Look up a PubChem compound
Look a compound up in PubChem by name, CID, SMILES or InChIKey. Returns PubChem records with CID, title, IUPAC name, SMILES, InChIKey, formula, molecular weight, XLogP, H-bond counts, TPSA and the PubChem URL. Names resolve to the best matches; use limit to get more than the top 5.
bylimitqueryrequiredCompute molecular properties
Calculate RDKit descriptors for a SMILES string. Returns molecular weight, Crippen LogP, H-bond donors/acceptors, TPSA, rotatable bonds, aromatic rings, heavy atoms, canonical SMILES and whether Lipinski's Rule of Five passes. Works for any valid SMILES, not only PubChem compounds.
smilesrequiredStandardize a structure
Standardize a structure: remove salts/counter-ions, neutralize charges, normalize functional groups, and return canonical SMILES of the parent.
smilesrequiredCompare two structures
Fingerprint similarity between two structures. Returns Tanimoto similarity on ECFP4 (Morgan radius 2, 2048 bits) and on MACCS keys. 1.0 means identical fingerprints; above ~0.7 on ECFP4 is a close analogue.
smiles_arequiredsmiles_brequiredSimilarity search (local index)
Find the compounds most similar to a structure in the local PubChem index. Exact fingerprint similarity (ECFP4/Morgan by default) over every indexed compound, best first, with CID, SMILES, InChIKey, IUPAC name, formula, MW and PubChem link. threshold is the minimum similarity (0-1, 0.7 finds close analogues; lower it to widen the search). Searches the index built with `pubchem-finder index build` (the first search loads it, which takes a while for a full PubChem index); until one is built, a demo set of about 1,900 FDA-approved drugs, with search_scope="demo" and a note to pass on to the user. group_by_scaffold adds the hits grouped by Bemis-Murcko scaffold, to see how many chemical series the hits span.
top_kmetricsmilesrequiredthresholdgroup_by_scaffoldSubstructure search (local index)
Find compounds in the local PubChem index that contain a fragment. query is a SMILES fragment (e.g. 'c1ccc2[nH]ccc2c1' for indoles) or, with query_type="smarts", a SMARTS pattern (e.g. '[NX3][SX4](=O)(=O)c' for aryl sulfonamides). Offline, exact (every hit is verified atom by atom; stereo is ignored) and not rate-limited, so prefer it over pubchem_substructure_search when index_status shows substructure: true. Without a local index it searches the demo set of FDA-approved drugs (search_scope="demo"). Hits come lowest CID first, which puts long-known compounds first. n_candidates bounds how many matches exist; exhaustive=false means more matches may exist beyond max_hits (1-1000) or the candidate limit. To show where the fragment sits, pass hits to draw_molecules with highlight="smarts" and the query as smarts.
queryrequiredmax_hitsquery_typeLocal index status
Report whether the local PubChem index is built, how many compounds it holds, its fingerprint, size, whether substructure search is available, what local searches cover now (search_scope: the index, or the built-in demo set of FDA-approved drugs) and how to build what is missing.
Takes no parameters.
PubChem similarity search
Find similar compounds across all of PubChem (~120M), live. Uses PubChem's own 2D fingerprint; threshold is a percentage (0-100, 90 finds close analogues). PubChem does not score hits, so each hit gets an ECFP4 Tanimoto to the query computed here and hits are sorted by it. Prefer the local similarity_search when an index is built: it is exact, scored and has no rate limits. max_records: 1-200.
smilesrequiredthresholdmax_recordsPubChem substructure search
Find compounds across all of PubChem that contain the given structure. The query is a SMILES fragment (e.g. 'c1ccc2[nH]ccc2c1' for indoles). Very generic fragments can time out; make the query more specific if so. Hits are sorted by ECFP4 similarity to the query, closest first. max_records: 1-200.
smilesrequiredmax_recordsPubChem exact structure match
Find the PubChem record(s) for exactly this structure. identity_type controls what counts as identical: same_stereo_isotope (default, strictest), same_stereo, same_isotope, same_connectivity (ignores stereo and isotopes, finds all stereoisomers), same_tautomer, nonconflicting_stereo.
smilesrequiredidentity_typePubChem synonyms and CAS numbers
Names a compound is known by (common, brand, systematic), most common first, plus its CAS Registry Numbers. Get the CID from pubchem_lookup.
cidrequiredlimitPubChem cross-references
Counts and examples of external identifiers linked to a compound: registry IDs (e.g. CAS, ChEMBL, DrugBank), PubMed articles (with links) and patents.
cidrequiredPubChem compound description
Short curated descriptions of a compound (what it is, what it is used for), each with its source.
cidrequiredPubChem page section
Curated information from one section of a compound's PubChem page. Sections: GHS Classification (pictograms, signal word, hazard statements), Hazards Identification, Pharmacology and Biochemistry, Mechanism of Action, Drug and Medication Information, Experimental Properties (melting point, solubility, measured LogP...), Toxicity, Use and Manufacturing, Food Additives and Ingredients. Each annotation names its source; cite it. Long sections are trimmed to max_chars (500-30000); truncated says when that happened. If the page lacks the section, the error lists the sections it has.
cidrequiredheadingrequiredmax_charsPubChem bioactivity summary
Summary of PubChem BioAssay results for a compound: how many assays, outcome counts, the targets with the most active results (UniProt accession, NCBI gene ID) and the most potent active measurements (µM).
cidrequiredDraw molecules
Draw 1-24 molecules as a PNG grid image the user can see. legends: one caption per molecule (names or CIDs). highlight: - "smarts": atoms matching the smarts pattern (e.g. a pharmacophore or an alert), - "diff": what each molecule adds relative to reference_smiles (atoms outside their maximum common substructure), with drawings aligned to the shared core, - "similarity_map": atom contributions to ECFP4 similarity with reference_smiles (green raises similarity, pink lowers it). Use it to show search hits, analogues or alerts instead of describing structures.
smartssmilesrequiredlegendshighlightreference_smilesMedicinal chemistry profile
Medicinal-chemistry triage of a structure: QED drug-likeness (0-1), synthetic accessibility (1 easy - 10 hard), Lipinski violations, Veber rules, PAINS/Brenk/NIH structural alerts with matched atom indices (pass them to draw_molecules with the alert as SMARTS, or just describe them), and the Bemis-Murcko scaffold.
smilesrequired90% of the applicable checks met
How complete this listing is, computed from the registry entry, the endpoint and public sources. Not a rating of the server and not a statement that it is safe or working today: reachability is a dated check, and no installs or reviews go into the score.
Declare the credential headers in the registry entry, or keep the endpoint answering the probe so its auth can be classified.
work.finderOfficial publisher
Finder Jobs's hosted MCP server, published by finder.work; no sign-in required; Streamable HTTP; 4 tools.
com.mambabuilt
Finds US importers and their overseas suppliers from customs bill of lading records, by company name, via an Apify actor.
Published by GitHub account gdangalov
A remote MCP server that helps an assistant find documented page-extraction services matching format, JavaScript, auth and price constraints, and record which…
Published by GitHub account Nero-Engine
Remote Apify-hosted MCP server that surfaces open EU tenders from TED, scored against your CPV codes and keywords, with past winners and prices.
Published by GitHub account theluckystrike
Passive subdomain enumeration from certificate transparency (certspotter, crt.sh) with DNS checks.
claude mcp add pubchem-finder -- uvx --python 3.14 pubchem-finder mcp/plugin install pubchem-finder --marketplace MysterionRise/pubchem-finder{ "mcpServers": { "pubchem-finder": { "command": "uvx", "args": ["--python", "3.14", "pubchem-finder", "mcp"] } }}uvx --python 3.14 pubchem-finder lookup caffeine # PubChem record by name, CID, SMILES or InChIKeyuvx --python 3.14 pubchem-finder props "CC(=O)Oc1ccccc1C(=O)O" # RDKit descriptors (offline)pubchem-finder index build --limit 1 --with-substructure # first PubChem chunk: ~445,000 compoundspubchem-finder search "CC(=O)Oc1ccccc1C(=O)O" --threshold 0.7 --top 20pubchem-finder search "CC(=O)Oc1ccccc1C(=O)O" --group-by-scaffoldpubchem-finder substructure "c1ccc2[nH]ccc2c1" # everything indexed that contains indolepubchem-finder substructure "[NX3][SX4](=O)(=O)c" --smarts # aryl sulfonamides, as SMARTSpubchem-finder index status
pubchem-finder index build --sdf my_library.sdf.gz # or index your own SDF filespubchem-finder pubchem similarity "CC(=O)Oc1ccccc1C(=O)O" --threshold 90 # across all of PubChempubchem-finder pubchem substructure "c1ccc2[nH]ccc2c1" --max 50pubchem-finder pubchem exact "CC(=O)Oc1ccccc1C(=O)O" --identity same_connectivitypubchem-finder pubchem synonyms 2244 # names and CAS numberspubchem-finder pubchem xrefs 2244 # registry IDs, PubMed articles, patentspubchem-finder pubchem describe 2244 # curated descriptions with sourcespubchem-finder pubchem annotations 2244 --heading "GHS Classification"pubchem-finder pubchem bioactivity 2244 # assay outcomes, top targets, most potent resultspubchem-finder draw "CC(=O)Oc1ccccc1C(=O)O" "COC(=O)c1ccccc1O" -l aspirin -l "methyl salicylate" \ --highlight diff --reference "CC(=O)Oc1ccccc1C(=O)O" -o analogues.pngpubchem-finder draw "O=C(O)c1ccccc1O" "CC(=O)Nc1ccc(O)cc1" --highlight similarity_map \ --reference "CC(=O)Oc1ccccc1C(=O)O" -o similarity.pngpubchem-finder triage "O=C1C(=Cc2ccccc2)SC(=S)N1" # QED, SA score, rules, PAINS/Brenk/NIH alerts
# .smi ("SMILES [id]" per line), .csv/.tsv with a smiles column, or - for stdin; CSV outpubchem-finder triage -i library.smi -o triage.csvpubchem-finder props -i library.csv -o props.csvpubchem-finder search -i queries.smi -o hits.csv --threshold 0.6 --top 50pubchem-finder substructure -i fragments.smi -o hits.csvfrom pubchem_finder import service
service.properties("CC(=O)Oc1ccccc1C(=O)O").molecular_weight # 180.16service.standardize("CC(=O)[O-].[Na+]").smiles # 'CC(=O)O'service.compare("CCO", "CCCO").ecfp4_tanimoto # 0.556service.lookup("caffeine").compounds[0].cid # 2519 (network)# Local searches use the demo set until an index is built.service.similarity_search("CC(=O)Oc1ccccc1C(=O)O", threshold=0.7)service.substructure_search("[NX3][SX4](=O)(=O)c", query_type="smarts")uv sync # create .venv and install everything, including dev toolsmake check # ruff lint + format check, mypy (strict), pytest with coveragemake test # just the testsPUBCHEM_LIVE=1 uv run pytest -m live # tests that call the real PubChem servicesuv run python scripts/smoke.py --live # every MCP tool through the real stdio serveruv run python scripts/smoke.py --url http://127.0.0.1:8000/mcp # same, against a running HTTP serverPubChem Compound SDF (HTTPS) --> streaming RDKit parse --> chunks/<chunk>.parquet (CID, SMILES, InChIKey, name, formula, MW) \-> chunks/<chunk>.h5 (FPSim2 fingerprints) \-> merge + popcount sort -> index/pubchem.h5 + manifest.jsonchunks/<chunk>.parquet SMILES --> RDKit pattern fingerprints --> chunks/pattern/<chunk>.h5 -> index/pubchem-pattern.h5 (only with --with-substructure)pubchem-finder CLI ----\ /-> FPSim2 exact similarity (in memory or on disk) + DuckDB over Parquet +--> service ---+--> FPSim2 pattern screen + RDKit atom match (substructure)MCP server (stdio|HTTP) / \-> PubChem PUG REST / PUG View for live data