PubChem Finder

PubChem Finder

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. It runs as a command-line tool, a Python library and an MCP server for Claude Desktop, Claude Code and other MCP clients.

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.

Why this one

Other PubChem tools, MCP servers 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:

• Exact, scored similarity search over every indexed compound (ECFP4 Tanimoto by default) in milliseconds, using FPSim2, the engine behind ChEMBL's similarity search.
• Local substructure search with SMILES or SMARTS: a fingerprint screen, then an atom-by-atom match, so every hit is a real match.
• Offline chemistry with RDKit: descriptors, standardization, PAINS/Brenk/NIH alerts, QED, synthetic accessibility, and drawings that show what changed between analogues.
• PubChem knowledge, cited: synonyms and CAS numbers, cross-references, GHS classification, pharmacology, toxicity and bioassay summaries, each with its source.

No database server, no Docker: the index is a pair of files in your data directory.

Use it from Claude

Requires uv, which fetches Python and everything else on first run.

Claude Code:

claude mcp add pubchem-finder -- uvx pubchem-finder mcp

or as a plugin, which also works in Cowork:

/plugin install pubchem-finder --marketplace MysterionRise/pubchem-finder

Claude Desktop (Settings, Developer, Edit Config, then restart Claude):

{
  "mcpServers": {
    "pubchem-finder": {
      "command": "uvx",
      "args": ["pubchem-finder", "mcp"]
    }
  }
}

Then ask things like:

• "What is the molecular weight and XLogP of caffeine? Is it Lipinski-compliant?"
• "Is ibuprofen hazardous? What does its GHS label say? Cite the sources."
• "What are the main targets of celecoxib in PubChem bioassays?"
• "Show me the closest analogues of aspirin and highlight what changed."
• "Does this compound have any PAINS alerts? O=C1C(=Cc2ccccc2)SC(=S)N1"
• With a local index: "Find the 20 compounds most similar to ibuprofen" or "Which indexed compounds contain an aryl sulfonamide? Draw a few with the group highlighted."

draw_molecules with highlight="smarts": eight sulfonamide drugs with the match for [NX3][SX4](=O)(=O)c highlighted, as Claude shows it inline.

The local-index tools need an index; build one from the command line (below) and the server picks it up. 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.

Tools

Use it from the command line

uvx pubchem-finder lookup caffeine                     # PubChem record by name, CID, SMILES or InChIKey
uvx pubchem-finder props "CC(=O)Oc1ccccc1C(=O)O"       # RDKit descriptors (offline)

uvx runs the latest release without installing it. To install the command once: uv tool install pubchem-finder (or pip install pubchem-finder). 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.

Build a local index and search it

pubchem-finder index build --limit 1 --with-substructure   # first PubChem chunk: ~445,000 compounds
pubchem-finder search "CC(=O)Oc1ccccc1C(=O)O" --threshold 0.7 --top 20
pubchem-finder search "CC(=O)Oc1ccccc1C(=O)O" --group-by-scaffold
pubchem-finder substructure "c1ccc2[nH]ccc2c1"              # everything indexed that contains indole
pubchem-finder substructure "[NX3][SX4](=O)(=O)c" --smarts  # aryl sulfonamides, as SMARTS
pubchem-finder index status

pubchem-finder index build --sdf my_library.sdf.gz         # or index your own SDF files

index build --limit N downloads the first N of PubChem's ~350 SDF chunks (about 500,000 CIDs each) 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.

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.

Ask PubChem directly

The pubchem commands query PubChem's live services, with no index needed:

pubchem-finder pubchem similarity "CC(=O)Oc1ccccc1C(=O)O" --threshold 90   # across all of PubChem
pubchem-finder pubchem substructure "c1ccc2[nH]ccc2c1" --max 50
pubchem-finder pubchem exact "CC(=O)Oc1ccccc1C(=O)O" --identity same_connectivity
pubchem-finder pubchem synonyms 2244          # names and CAS numbers
pubchem-finder pubchem xrefs 2244             # registry IDs, PubMed articles, patents
pubchem-finder pubchem describe 2244          # curated descriptions with sources
pubchem-finder pubchem annotations 2244 --heading "GHS Classification"
pubchem-finder pubchem bioactivity 2244       # assay outcomes, top targets, most potent results

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).

Pictures, triage and whole files

pubchem-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.png
pubchem-finder draw "O=C(O)c1ccccc1O" "CC(=O)Nc1ccc(O)cc1" --highlight similarity_map \
    --reference "CC(=O)Oc1ccccc1C(=O)O" -o similarity.png
pubchem-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 out
pubchem-finder triage -i library.smi -o triage.csv
pubchem-finder props -i library.csv -o props.csv
pubchem-finder search -i queries.smi -o hits.csv --threshold 0.6 --top 50
pubchem-finder substructure -i fragments.smi -o hits.csv

Rows that fail in batch mode get an error column instead of stopping the run.

--highlight diff: each analogue is aligned to the core it shares with aspirin, and the atoms it adds are highlighted.

--highlight similarity_map: atoms that raise ECFP4 similarity to aspirin in green, atoms that lower it in pink.

How big is it?

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.

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.

Use it from Python

The CLI and MCP server are thin layers over pubchem_finder.service:

from pubchem_finder import service

service.properties("CC(=O)Oc1ccccc1C(=O)O").molecular_weight  # 180.16
service.standardize("CC(=O)[O-].[Na+]").smiles  # 'CC(=O)O'
service.compare("CCO", "CCCO").ecfp4_tanimoto  # 0.556
service.lookup("caffeine").compounds[0].cid  # 2519 (network)
service.similarity_search("CC(=O)Oc1ccccc1C(=O)O", threshold=0.7)  # needs an index
service.substructure_search("[NX3][SX4](=O)(=O)c", query_type="smarts")

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.

Troubleshooting

• The first run takes a minute. uv downloads Python if needed and a few hundred MB of packages (RDKit, PyArrow, DuckDB...) once; later runs start in about a second.
• Claude Desktop says the server failed to start. Desktop apps on macOS do not see your shell's 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.
• "No local index" from similarity_search or substructure_search: build one with pubchem-finder index build --limit 1 (add --with-substructure for substructure search). index_status says what is missing.
• PubChem is slow or busy. Requests are throttled to PubChem's limit of 5 per second and retried when PubChem is busy. Structure searches across all of PubChem can time out on very generic fragments; use a more specific query, or the local index.
• Behind a proxy: set HTTPS_PROXY; all requests to PubChem and NCBI honour it.
• Linux on ARM (aarch64): FPSim2 publishes no wheel there, so installing needs a C++ compiler to build it.
• Starting over: pubchem-finder cache clear empties the response cache; deleting the data directory removes the index too.

Data, credits and citation

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.

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).

Development

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.

uv sync            # create .venv and install everything, including dev tools
make check         # ruff lint + format check, mypy (strict), pytest with coverage
make test          # just the tests
PUBCHEM_LIVE=1 uv run pytest -m live   # tests that call the real PubChem services
uv run python scripts/smoke.py --live  # every MCP tool through the real stdio server
uv run python scripts/smoke.py --url http://127.0.0.1:8000/mcp  # same, against a running HTTP server

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.

PubChem 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.json
chunks/<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

This repository started in 2020 as an Indigo + Elasticsearch indexer for PubChem dumps; that code is in the git history before commit 06619d9.

License

MIT. See LICENSE.