@cyanheads/chembl-mcp-server
Link compounds to protein targets, rank bioactivity (IC50/Ki/EC50), and look up drug mechanisms and indications over ChEMBL via MCP. STDIO or Streamable HTTP.
8 Tools (+1 opt-in) • 2 Resources
Overview
Drug-discovery data from ChEMBL (EBI): the curated link between compounds, protein targets, and measured bioactivity (IC50/Ki/EC50), plus drug mechanisms and indications. Search compounds by name, ID, or structure, resolve targets, and rank the most potent measurements.
Tools
Resources
All resource data is also reachable via the tools, so tool-only MCP clients lose nothing. There are no prompts — the canonical workflows are short tool chains an agent composes directly, and the cross-server chain guidance ships as server-level instructions instead.
Skills
Capability reference
chembl_search_molecules tool
- Default
search_type=name matches drug names, synonyms, ChEMBL IDs, and InChIKeys in one query; a query that is exactly a ChEMBL ID or InChIKey routes to ChEMBL's single-record lookup instead of the fuzzy text index (totalCount: 1)
- Structure search via
search_type: exact, similarity (Tanimoto ≥ similarity_threshold, integer 40–100, default 70), or substructure — supply structure as a SMILES. max_phase_min restricts any search type to compounds at or above a max clinical phase (4 keeps every drug that reached approval, withdrawn ones included, since max_phase stays 4 after a withdrawal). A similarity_threshold other than the default on a search type that ignores it is named as ignored in the notice. A SMILES ChEMBL cannot parse fails a similarity or substructure search on the first request as invalid_structure, not as an outage
- Every row carries
max_phase, MW, AlogP, Lipinski rule-of-five violations, and QED; only search_type=similarity results carry a Tanimoto similarity percent — absent, not null, on other modes
- Every row also carries
parent_chembl_id, the parent of its family: ERLOTINIB HYDROCHLORIDE (CHEMBL1079742) names CHEMBL553, and a compound with no recorded hierarchy names itself. A salt can rank ahead of its parent while holding a small share of the family's measurements
- Paginated via
nextCursor / cursor, omitted (not null) on the last page — redeem a cursor with the same filters that minted it; a limit above 100 is served at 100, with a notice
- ChEMBL stops counting and paging a name search at 10,000 matches and a substructure search at 30,000; a total at that ceiling comes back as
totalCountCapped: true with a notice that at least that many match and the rest are out of reach — narrow the query to get under it. ChEMBL applies max_phase_min to only the first 30,000 hits of a substructure search, so a filtered total from a structure that reaches that ceiling is also a lower bound, flagged the same way
- Chain
molecule_chembl_id into chembl_get_bioactivities or chembl_get_drug_info
chembl_get_bioactivities tool
- Supply at least one of
molecule_chembl_id or target_chembl_id; supplying both narrows to that compound–target pair — neither is a missing_filter error
include_alternate_forms: true widens molecule_chembl_id to its family — the parent and every salt and other alternate form ChEMBL files under it (imatinib CHEMBL941: 4,878 measurements alone, 5,802 across its forms); a salt's ID reaches the same family, and each row keeps the form it was measured on. The count, both views, cursor pages, and the spill read the same family; re-send the flag with a cursor. Without molecule_chembl_id the flag is an alternate_forms_without_molecule error
- IDs are matched in canonical form:
"chembl941" and " CHEMBL941 " read as CHEMBL941, and a value that is no ChEMBL ID ("imatinib") fails with -32602 before any request, routing to the search tools — for molecule_chembl_id, when include_alternate_forms is off and the value goes straight to the filter
- Filter by
standard_type (IC50/Ki/EC50/…), pchembl_value_min, assay_type, organism, and variant; ranked on pchembl_value — comparable only within one standard_type
assay_type takes a code (B / F / A / T / P / U) or ChEMBL's name for it (binding, ADMET, …) in any case. standard_type matches exactly, case included — ChEMBL holds distinct types that differ only by case (Kd / KD) — and when nothing matches, the notice names a case variant ChEMBL records under the same filters ("ic50" → IC50)
variant separates wild-type from mutant potency: "wild_type" keeps the measurements that record no variant, and any other value matches the whole recorded variant case-insensitively ("T315I", "F508del", "L858R,T790M" in ChEMBL's order, "UNDEFINED MUTATION") — "L858R" alone does not match "L858R,T790M"
- Each row carries
activity_comment (e.g. Not Active, often the only result when no value was measured) and data_validity_comment (e.g. Outside typical range), the assay's assay_variant_mutation, assay_variant_accession, and bao_label (the assay format, not the target type), the family parent_molecule_chembl_id (merge a drug with its salts on it), ChEMBL's potential_duplicate flag (a likely repeat citation of an earlier document's value; filter on potential_duplicate IS NOT TRUE before counting measurements per compound, which keeps a row whose flag is null), and the source document_chembl_id and document_year for citation — pass the ID to chembl_get_documents for the paper
potency_view selects potency_ranked (default, measurements with a derivable pchembl_value) or null_potency (the excluded rows); pchembl_value_min with null_potency is a contradictory_potency_filter error, and totalCount spans both views
- Numerics are coerced to
number | null at the service boundary — a missing potency reads as null, never 0
- Large sets spill to a DataCanvas table per view (
bioactivities / bioactivities_null_potency); the canvas is on by default, and CANVAS_PROVIDER_TYPE=none turns it off
- The spill fetches its pages
CHEMBL_MAX_CONCURRENT_PAGES at a time (default 4) and stays inside a row cap, CHEMBL_MAX_SPILL_ROWS (default 50,000), and a time budget, CHEMBL_SPILL_DEADLINE_MS (default 45 s). When either bound stops it short of the view, the response reports truncated: true, staged_row_count, and truncated_by (row_cap or time_budget)
- The inline preview is always capped at
limit (default 25) regardless of spill status; a limit above 1,000 is served at 1,000, with a notice
- A canvas is minted only when the view spills, so an inline fit holds no canvas; pass the returned
canvas_id back and each later non-cursor call re-stages that view's table with its own rows — even when they fit inline or none match — replacing the prior rows, while the other view's table stays put. A spill replaces the table only once it succeeds, so one that fails or is cancelled leaves the prior rows. At the per-tenant canvas cap, a spill without canvas_id fails as canvas_capacity_exhausted
- Whenever a call stages nothing (the canvas is disabled, or the view fit inline with no
canvas_id), the view comes back a page at a time via nextCursor / cursor, omitted (not null) on the last page — redeem a cursor with the same filters and potency_view that minted it; a cursor page is served inline and never staged, even with the canvas enabled
chembl_search_targets tool
- Supply at least one of
accession (UniProt, e.g. P00533), gene_symbol, or query (a free-text name, or a ChEMBL target ID in any case such as CHEMBL203, which reads that one target); narrow with organism and target_type — none supplied is a missing_input error
- A UniProt accession is the most precise input — chain it from a
uniprot/protein server. accession and target_type are matched uppercase, the form ChEMBL records ("p00533" reads as P00533, "single protein" as SINGLE PROTEIN); gene_symbol and organism already match case-insensitively
- Each row carries target type, organism, and component UniProt accessions + gene symbols, flattened from ChEMBL's nested component synonyms
- Paginated via
nextCursor / cursor, the same contract as chembl_search_molecules, limit clamp included
- Chain
target_chembl_id into chembl_get_bioactivities
chembl_get_drug_info tool
- Supply
molecule_chembl_id (any case) or the molecule's standard InChIKey; returns mechanism(s) of action, molecular target(s), action type, max phase, first-approval year, withdrawn and black_box_warning flags with ChEMBL's warning records, and clinical indications with the max phase reached for each
- Both flags and every list cover the drug's family under
parent_molecule_chembl_id, since ChEMBL often records a drug's mechanisms, approved indications, and warnings on a salt: erlotinib CHEMBL553 and its hydrochloride return the same EGFR mechanism, recorded on CHEMBL1079742. Each mechanism and warning names the form it is recorded on; each indication appears once per MeSH/EFO pair at the highest phase any form reached, listing each form at its own phase (sorafenib's hepatocellular carcinoma is phase 4 on its tosylate CHEMBL1200485, phase 2 on its deuterated analog donafenib CHEMBL4297490)
max_phase and first_approval are the queried form's own record, never the family's: ChEMBL files deuterated and radiolabelled analogs under their parent, so the family's highest phase would read asandeutertinib (CHEMBL6068008, phase 2) as its parent osimertinib's approved drug, and deutetrabenazine (approved 2017) would take tetrabenazine's 2008. A salt can record a lower phase than its parent (almitrine mesylate CHEMBL3181957 is −1, almitrine 4); pass parent_molecule_chembl_id back for the parent's own
max_phase 4 means the form reached approval and stays 4 after a withdrawal: withdrawn says whether any form of the family, deuterated analogs included, was pulled from a market in at least one country, and each warnings record (type Withdrawn or Black Box Warning) gives the class, country, year, reason, cited sources, and the form it is filed on. Read both before treating a phase-4 drug as on the market
- The molecule record is fetched first and fails the call if it fails; mechanisms, indications, warnings, and the family's flags follow concurrently with
Promise.allSettled, so a failed list degrades to a disclosed partial result rather than failing the call. When the family read fails or is cut short, the notice says so, and a null flag is unknown, not false
- Each list carries its own
mechanisms_status / indications_status / warnings_status (complete / truncated / failed) next to a *_total_count — an empty array is authoritative only when the status is complete. A failed list's *_failure says whether it ran out of time (timeout) or ChEMBL answered with an error (upstream_error); a truncated indication list reports indications_rows_fetched, which bounds the indications missing, and its shown phases and forms are lower bounds
- A mechanism's
target_chembl_id chains into chembl_get_bioactivities
chembl_get_assay tool
- Supply
assay_chembl_ids from chembl_get_bioactivities rows — one ID or a list of 1–1,000, any case; the singular assay_chembl_id is accepted as an alias. A value that is no ChEMBL ID fails with -32602 before any request
- The first 100 distinct IDs go out as one upstream request and come back as
assays in the order given; the rest are named in deferred_ids to pass in another call. An ID ChEMBL holds no assay for (a compound, target, or document ID included) lands in not_found_ids and the call still succeeds, with a notice
- Returns description, assay type (binding / functional / ADMET / toxicity), BioAssay Ontology format, the target measured, organism, cell type, tissue, strain, source
document_chembl_id, and ChEMBL's 0–9 confidence score (9 = direct single protein target, 8 = homologous single protein, 7–4 = protein complexes or multiple proteins, 3–1 = a non-protein, subcellular, or non-molecular target, 0 = no target assigned yet, with target_chembl_id then a placeholder such as Unchecked or ADMET)
- Call it to judge whether two measurements are comparable before ranking them together
chembl_get_documents tool
- Supply
document_chembl_ids from the document_chembl_id of chembl_get_bioactivities rows or chembl_get_assay records — one ID or a list of 1–1,000, any case; the singular document_chembl_id is accepted as an alias
- The first 100 distinct IDs go out as one upstream request and come back as
documents in the order given; the rest are named in deferred_ids. An ID ChEMBL holds no document for (an unknown ID, or a compound, target, or assay ID) lands in not_found_ids and the call still succeeds, with a notice
- Each document carries
doc_type (PUBLICATION, PATENT, DATASET, or BOOK), title, authors, journal, year, volume, issue, first_page, last_page, pubmed_id (a digit string, the form a PubMed server takes), doi, and patent_id. Every field but the ID is null when ChEMBL records none: a patent carries no journal, PMID, or DOI, and 10.6019/ DOIs belong to datasets deposited with ChEMBL
- Chain
pubmed_id or doi into a PubMed or Crossref server for the abstract
chembl_dataframe_query tool
- Accepts a single read-only
SELECT against a canvas_id from a chembl_get_bioactivities call that staged a table; writes, DDL, and non-SELECT statements are rejected by the framework SQL gate
- Reference each staged table by the name
chembl_get_bioactivities returned — bioactivities (potency_ranked) or bioactivities_null_potency (null_potency); discover columns with chembl_dataframe_describe first
- Every row the SQL returns comes back on both
structuredContent.rows and the content[] markdown table, so size the result in the SQL itself: project the columns you need and set a LIMIT
- The canvas engine's own query-result cap is the only server-side ceiling, disclosed as
truncated: true with row_count rows returned; page past it with ORDER BY a unique column (e.g. activity_id) and LIMIT/OFFSET written into the query in place of any LIMIT it has — offsets reach rows beyond the cap
- Fails with
canvas_disabled when the server runs with CANVAS_PROVIDER_TYPE=none
chembl_dataframe_describe tool
- Supply a
canvas_id from a chembl_get_bioactivities call that staged a table
- Returns each staged table/view with its row count, kind, and column names + types
- Fails with
canvas_disabled when the server runs with CANVAS_PROVIDER_TYPE=none
chembl_dataframe_drop tool
- Opt-in — registered only when
CHEMBL_DATAFRAME_DROP_ENABLED=true; absent from tools/list when off, though it still appears in the server manifest carrying the enable hint
- Drops a named staged table by
canvas_id + table_name; returns dropped: true if it existed, false if the live canvas holds no table by that name
- An unknown or expired
canvas_id fails as canvas_not_found — an expired canvas has already freed its tables, so there is nothing left to drop
- Rarely needed — a staged table lives as long as its canvas, which expires on its sliding TTL (
CANVAS_TTL_MS, default 24 h) or its absolute cap (CANVAS_ABSOLUTE_CAP_MS, default 7 days) and frees every table on it; reach for it only to free a large table early in a long session
- Fails with
canvas_disabled when the server runs with CANVAS_PROVIDER_TYPE=none
chembl://molecule/{chemblId} resource
- Molecule record as
application/json — the same shape a chembl_search_molecules row carries (ID, names, structures, properties, max clinical phase, family parent_chembl_id)
chemblId is a ChEMBL ID in any case (chembl://molecule/chembl25 reads as CHEMBL25); anything else is rejected before a fetch
- Fully covered by the tool surface — a convenience injectable-context mirror of the per-record fetch
chembl://target/{chemblId} resource
- Target record as
application/json — preferred name, type, organism, and component UniProt accessions + gene symbols
chemblId is a ChEMBL ID in any case (chembl://target/chembl203 reads as CHEMBL203); anything else is rejected before a fetch
- Fully covered by the tool surface — a convenience injectable-context mirror of the per-record fetch
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.
ChEMBL-specific:
- Bidirectional bioactivity bridge — one tool serves both compound→target and target→compound, ranked on
pchembl_value
- Structure search (exact / similarity / substructure) consolidated under one discovery tool via a
search_type enum
- String →
number | null numeric coercion at the service boundary — a missing potency becomes null, never 0
- DataCanvas spill on the flagship tool — tens-of-thousands-of-row activity sets stream to a DuckDB table you inspect with
chembl_dataframe_describe and query via chembl_dataframe_query
- Server-level
instructions carry the cross-server chain guidance and the ChEMBL CC BY-SA 3.0 attribution requirement
Agent-friendly output:
- Provenance on every response — total-found counts, applied-filter echo, and a spill notice so agents know whether the preview is the full set or a slice of a canvas table
- Truncation disclosure — capped searches report
shown / cap / totalCount (with totalCountCapped: true when the total is ChEMBL's own search ceiling, a lower bound), and spilled tables report truncated + staged_row_count + truncated_by, so a page or slice is never mistaken for the complete set
- Bounded latency — every call holds its upstream requests, retries included, to one 45 s budget, so a hung upstream fails as
upstream_timeout before an MCP client's 60 s timeout; a spill's budget is CHEMBL_SPILL_DEADLINE_MS (default 45 s), and at expiry the rows fetched so far stage with truncated_by: "time_budget"
- Typed, recoverable errors —
missing_filter / missing_input / invalid_structure / not_a_chembl_id / alternate_forms_without_molecule / contradictory_potency_filter / canvas_disabled / canvas_capacity_exhausted carry recovery hints, so callers correct the call without parsing prose
- Input-edge normalization — IDs, accessions, target types, and assay-type names are brought to the form ChEMBL records before any request, and each advertised input pattern admits the case and whitespace variants the server maps, so a JSON-Schema-validating client can send them too
- Inert upstream text — every ChEMBL string a
format() prints is escaped so a CommonMark reader of content[] sees the text as recorded, not a link, emphasis, or block made from it ([125I](R)-DOI in an assay description stays text); SMILES and InChIKeys render as code spans, and structuredContent keeps every value as ChEMBL wrote it
- Never fabricates — normalization and
format() preserve null potency / units; a missing measurement renders as "not reported", never 0
Getting started
Public Hosted Instance
A public instance is available at https://chembl.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
Self-Hosted / Local
ChEMBL is keyless — no API key or account is required.
Add the following to your MCP client configuration file:
Or with npx (no Bun required):
Or with Docker:
For Streamable HTTP, set the transport and start the server:
The analytical SQL path (the bioactivities spill and the chembl_dataframe_* tools) runs on DuckDB by default; add "CANVAS_PROVIDER_TYPE": "none" to the env to turn it off.
Prerequisites
Installation
- Clone the repository:
- Navigate into the directory:
- Install dependencies:
- Configure environment:
Configuration
An invalid value of any variable, CHEMBL_* (validated by the Zod schema in src/config/server-config.ts) or the framework's, stops the server at startup with a configuration banner naming it. A blank value falls back to its default. ChEMBL is keyless, so every variable is optional.
See .env.example for the full list of optional overrides.
Installed as a Claude Code plugin, a Codex plugin, or the Claude Desktop .mcpb bundle, the server takes the CANVAS_PROVIDER_TYPE, CHEMBL_*, and MCP_LOG_LEVEL settings above without an env block: the Claude Code plugin and the .mcpb bundle declare them as install options (in Claude Code, /plugin configure changes them later), Codex forwards them from the environment it runs in, and an option left blank keeps its default. The .mcpb bundle ships without DuckDB's native binding, so it fixes CANVAS_PROVIDER_TYPE to none, runs with the canvas off, and leaves out the options that only matter with it on (CANVAS_PROVIDER_TYPE, CHEMBL_DATAFRAME_DROP_ENABLED, CHEMBL_MAX_SPILL_ROWS, CHEMBL_MAX_CONCURRENT_PAGES, CHEMBL_SPILL_DEADLINE_MS); use an npx or bunx install for the SQL path.
Running the server
Local development
-
Build and run:
-
Run checks and tests:
Docker
The Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/chembl-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them. Dependency installation and security scanning run on the builder's native platform, with Bun's --cpu and --os selecting DuckDB bindings for the target linux/amd64 or linux/arm64 image. The slim runtime receives that production dependency tree, so the default DuckDB canvas works on either image architecture.
Project structure
Development guide
See CLAUDE.md/AGENTS.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, ctx.state for tenant-scoped storage
- Register new tools and resources in the
createApp() arrays
- Wrap the ChEMBL API: validate raw → normalize to the flat domain type → return the output schema; never fabricate missing fields (absent numerics become
null, never 0)
Contributing
Issues are welcome. Run checks and tests before submitting:
License
Apache-2.0 — see LICENSE for details.