io.github.cyanheads/chembl-mcp-server

Official7 toolsLive

by cyanheads · TypeScript

Link compounds to protein targets, rank bioactivity, and look up drug mechanisms and indications.

@cyanheads/chembl-mcp-server (MCP)

This Model Context Protocol (MCP) server looks up drug information in ChEMBL. It links compounds to protein targets, ranks bioactivity using values such as IC50/Ki/EC50, and retrieves drug mechanisms and indications. The server supports connections via STDIO or Streamable HTTP and provides 7 tools (+1 opt-in).

🛠️ Key Features

Compound-to-protein target linking
Bioactivity ranking (IC50/Ki/EC50)
Drug mechanism and indication lookup
Access via STDIO or Streamable HTTP
7 tools (+1 opt-in)

🚀 Use Cases

Querying compound targets for protein-level associations
Comparing bioactivity potency using IC50/Ki/EC50
Finding mechanisms and indications for drug candidates based on ChEMBL

⚡ Developer Benefits

MCP integration (toolCount: 7 tools + optional tool)
Topics include bioactivity, chembl, cheminformatics, compounds, medicinal-chemistry, protein-targets, and TypeScript

⚠️ Limitations

Scope is described as ChEMBL-based lookup; behavior beyond compound linking, bioactivity ranking, and drug mechanisms/indications is not specified.

Topics

bioactivitychemblcheminformaticscompoundscyanheadsdrug-discoverymcpmedicinal-chemistrymodel-context-protocolprotein-targetstypescript

Captured live from the server via tools/list.

chembl_search_molecules

Discovery entry point for compounds. Find by name / ChEMBL ID / InChIKey with the default search_type=name (supply query), or run a structure search with search_type exact | similarity | substructure (supply structure as a SMILES). At least one of query or structure is required, and structure is required for the three structure modes. Returns ChEMBL ID, preferred name, canonical SMILES, formula, MW, AlogP, Lipinski violations, QED, and max clinical phase on every row; only search_type=similarity adds a Tanimoto similarity percent. Chain molecule_chembl_id into chembl_get_bioactivities or chembl_get_drug_info. A capped result carries nextCursor — pass it back as cursor with the same filters to read the next page.

Parameters7

query	string	optional	Search text for search_type=name — a drug name, ChEMBL ID, or InChIKey, e.g. "imatinib" or "CHEMBL25".
structure	string	optional	SMILES string for structure search, e.g. "CC(=O)Oc1ccccc1C(=O)O". Required when search_type is exact/similarity/substructure.
search_type	string	optional	name = text lookup (query); exact = exact structure match; similarity = Tanimoto ≥ threshold; substructure = contains the structure. All structure modes need `structure`.
similarity_threshold	integer	optional	Minimum Tanimoto similarity percent for search_type=similarity (40–100; ChEMBL rejects below 40). Ignored for other modes.
max_phase_min	integer	optional	For search_type=name, restrict to compounds at or above this max clinical phase (e.g. 4 for marketed drugs only).
limit	integer	optional	Maximum molecules to return. Defaults to the server default (25) when omitted.
cursor	string	optional	Opaque continuation token from a previous call's nextCursor — resumes where that page ended. Omit for the first page. Re-send the same query/structure/filters that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Search text for search_type=name — a drug name, ChEMBL ID, or InChIKey, e.g. \"imatinib\" or \"CHEMBL25\".",
      "type": "string"
    },
    "structure": {
      "description": "SMILES string for structure search, e.g. \"CC(=O)Oc1ccccc1C(=O)O\". Required when search_type is exact/similarity/substructure.",
      "type": "string"
    },
    "search_type": {
      "default": "name",
      "description": "name = text lookup (query); exact = exact structure match; similarity = Tanimoto ≥ threshold; substructure = contains the structure. All structure modes need `structure`.",
      "type": "string",
      "enum": [
        "name",
        "exact",
        "similarity",
        "substructure"
      ]
    },
    "similarity_threshold": {
      "default": 70,
      "description": "Minimum Tanimoto similarity percent for search_type=similarity (40–100; ChEMBL rejects below 40). Ignored for other modes.",
      "type": "integer",
      "minimum": 40,
      "maximum": 100
    },
    "max_phase_min": {
      "description": "For search_type=name, restrict to compounds at or above this max clinical phase (e.g. 4 for marketed drugs only).",
      "type": "integer",
      "minimum": 0,
      "maximum": 4
    },
    "limit": {
      "description": "Maximum molecules to return. Defaults to the server default (25) when omitted.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Opaque continuation token from a previous call's nextCursor — resumes where that page ended. Omit for the first page. Re-send the same query/structure/filters that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

chembl_get_bioactivities

The flagship compound↔target bioactivity bridge: measurements for a molecule (target deconvolution / selectivity), a target (lead finding), or both together (how potently one compound hits one target). Supply at least one of molecule_chembl_id (from chembl_search_molecules) or target_chembl_id (from chembl_search_targets) — supplying both narrows to that compound–target pair, supplying neither is an error. Filter by standard_type (IC50/Ki/EC50/…), minimum potency pchembl_value_min, assay_type, and organism. Not every measurement has a derivable pchembl_value, so potency_view picks which side of that split you get: the default "potency_ranked" returns the measurements that have one, most potent first (ChEMBL sorts the rest first otherwise, which is why they are not merged), and "null_potency" returns exactly the measurements that have none. totalCount is the honest full match count across both views either way. Mixing measurement types (IC50 vs Ki) is a scientific error — set standard_type to compare like with like. A popular target carries tens of thousands of rows: results spill to a DataCanvas table (call chembl_dataframe_describe for its columns, then chembl_dataframe_query for honest aggregates across the staged set), while an inline preview answers the immediate question. Each view stages its own table (bioactivities / bioactivities_null_potency), so running both against one canvas_id lets a UNION ALL rebuild the full set. The staged table is capped at CHEMBL_MAX_SPILL_ROWS; when the cap is hit, truncated is true and the table is a bounded slice, not the complete view. The inline rows are always capped at limit, so compare that against totalCount before treating them as the whole answer. Spilling the rest requires CANVAS_PROVIDER_TYPE=duckdb; without it the inline preview is all there is.

Parameters9

molecule_chembl_id	string	optional	ChEMBL molecule ID (from chembl_search_molecules), e.g. "CHEMBL941". Supply this, target_chembl_id, or both — both narrows to that compound–target pair.
target_chembl_id	string	optional	ChEMBL target ID (from chembl_search_targets), e.g. "CHEMBL203". Supply this, molecule_chembl_id, or both — both narrows to that compound–target pair.
standard_type	string	optional	Restrict to one measurement type, e.g. "IC50", "Ki", "EC50". Set this to compare potencies validly.
pchembl_value_min	number	optional	Minimum pchembl_value (−log10 molar potency), e.g. 7 keeps sub-100 nM activities. Only valid on the potency_ranked view — the null_potency rows have no pchembl_value to compare against.
potency_view	string	optional	Which side of the pchembl_value presence split to retrieve. "potency_ranked" (default) returns the measurements that have a derivable pchembl_value, most potent first. "null_potency" returns exactly the measurements that have none — the rows the ranked view excludes, otherwise unreachable. The two partition the match set and stage to separate canvas tables.
assay_type	string	optional	Restrict to an assay type code: "B" (binding), "F" (functional), "A" (ADMET), "T" (toxicity).
organism	string	optional	Restrict to a target organism, e.g. "Homo sapiens" (case-insensitive exact match).
limit	integer	optional	Maximum rows in the inline preview. Defaults to the server default (25). The full set still spills to the canvas.
canvas_id	string	optional	Optional canvas ID from a prior call to reuse the same canvas. Each potency_view re-stages its own table, so a second query of the SAME view REPLACES (overwrites) its prior rows — it does not append — while the other view's table is left intact, which is what lets both coexist on one canvas. Omit to mint a fresh canvas.

Raw schema

{
  "type": "object",
  "properties": {
    "molecule_chembl_id": {
      "description": "ChEMBL molecule ID (from chembl_search_molecules), e.g. \"CHEMBL941\". Supply this, target_chembl_id, or both — both narrows to that compound–target pair.",
      "type": "string"
    },
    "target_chembl_id": {
      "description": "ChEMBL target ID (from chembl_search_targets), e.g. \"CHEMBL203\". Supply this, molecule_chembl_id, or both — both narrows to that compound–target pair.",
      "type": "string"
    },
    "standard_type": {
      "description": "Restrict to one measurement type, e.g. \"IC50\", \"Ki\", \"EC50\". Set this to compare potencies validly.",
      "type": "string"
    },
    "pchembl_value_min": {
      "description": "Minimum pchembl_value (−log10 molar potency), e.g. 7 keeps sub-100 nM activities. Only valid on the potency_ranked view — the null_potency rows have no pchembl_value to compare against.",
      "type": "number"
    },
    "potency_view": {
      "default": "potency_ranked",
      "description": "Which side of the pchembl_value presence split to retrieve. \"potency_ranked\" (default) returns the measurements that have a derivable pchembl_value, most potent first. \"null_potency\" returns exactly the measurements that have none — the rows the ranked view excludes, otherwise unreachable. The two partition the match set and stage to separate canvas tables.",
      "type": "string",
      "enum": [
        "potency_ranked",
        "null_potency"
      ]
    },
    "assay_type": {
      "description": "Restrict to an assay type code: \"B\" (binding), \"F\" (functional), \"A\" (ADMET), \"T\" (toxicity).",
      "type": "string"
    },
    "organism": {
      "description": "Restrict to a target organism, e.g. \"Homo sapiens\" (case-insensitive exact match).",
      "type": "string"
    },
    "limit": {
      "description": "Maximum rows in the inline preview. Defaults to the server default (25). The full set still spills to the canvas.",
      "type": "integer",
      "minimum": 1,
      "maximum": 1000
    },
    "canvas_id": {
      "description": "Optional canvas ID from a prior call to reuse the same canvas. Each potency_view re-stages its own table, so a second query of the SAME view REPLACES (overwrites) its prior rows — it does not append — while the other view's table is left intact, which is what lets both coexist on one canvas. Omit to mint a fresh canvas.",
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

chembl_search_targets

Resolve a protein/gene/UniProt accession to the ChEMBL target ID that chembl_get_bioactivities needs for the target→leads workflow. Supply at least one of accession (UniProt, e.g. P00533), gene_symbol (e.g. EGFR), or query (free-text name); filter further by organism and target_type. Returns each target with its type, organism, and component UniProt accessions + gene symbols. A UniProt accession from the uniprot/protein server is the most precise input. A capped result carries nextCursor — pass it back as cursor with the same filters to read the next page.

Parameters7

query	string	optional	Free-text name match against the target preferred name, e.g. "kinase" or "growth factor receptor".
accession	string	optional	UniProt accession of a target component, e.g. "P00533". The most precise resolver — from the uniprot/protein server.
gene_symbol	string	optional	Gene symbol of a target component, e.g. "EGFR" (case-insensitive exact match).
organism	string	optional	Restrict to a source organism, e.g. "Homo sapiens" (case-insensitive exact match).
target_type	string	optional	Restrict to a target class, e.g. "SINGLE PROTEIN" or "PROTEIN COMPLEX".
limit	integer	optional	Maximum targets to return. Defaults to the server default (25) when omitted.
cursor	string	optional	Opaque continuation token from a previous call's nextCursor — resumes where that page ended. Omit for the first page. Re-send the same accession/gene_symbol/query/filters that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set.

Raw schema

{
  "type": "object",
  "properties": {
    "query": {
      "description": "Free-text name match against the target preferred name, e.g. \"kinase\" or \"growth factor receptor\".",
      "type": "string"
    },
    "accession": {
      "description": "UniProt accession of a target component, e.g. \"P00533\". The most precise resolver — from the uniprot/protein server.",
      "type": "string"
    },
    "gene_symbol": {
      "description": "Gene symbol of a target component, e.g. \"EGFR\" (case-insensitive exact match).",
      "type": "string"
    },
    "organism": {
      "description": "Restrict to a source organism, e.g. \"Homo sapiens\" (case-insensitive exact match).",
      "type": "string"
    },
    "target_type": {
      "description": "Restrict to a target class, e.g. \"SINGLE PROTEIN\" or \"PROTEIN COMPLEX\".",
      "type": "string"
    },
    "limit": {
      "description": "Maximum targets to return. Defaults to the server default (25) when omitted.",
      "type": "integer",
      "minimum": 1,
      "maximum": 100
    },
    "cursor": {
      "description": "Opaque continuation token from a previous call's nextCursor — resumes where that page ended. Omit for the first page. Re-send the same accession/gene_symbol/query/filters that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set.",
      "type": "string"
    }
  },
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

chembl_get_drug_info

Pharmacology for a drug (molecule): mechanism(s) of action, the molecular target(s) it acts on, action type (inhibitor / agonist / …), first-approval year, and clinical indications with the max phase reached for each. Supply molecule_chembl_id (from chembl_search_molecules). Distinct from the openfda server's label/adverse-event view — this is the curated mechanism-and-indication record. A mechanism's target_chembl_id chains into chembl_get_bioactivities for compounds hitting the same target. Each list carries its own retrieval state: an empty mechanisms or indications array means the molecule has none recorded only when the matching mechanisms_status / indications_status is "complete" — "failed" means the upstream request was rejected and the array says nothing about the molecule, and "truncated" means the page cap bounded the list at fewer rows than the matching *_total_count.

Parameters1

molecule_chembl_id

string

required

ChEMBL molecule ID (from chembl_search_molecules), e.g. "CHEMBL939" for gefitinib.

Raw schema

{
  "type": "object",
  "properties": {
    "molecule_chembl_id": {
      "type": "string",
      "minLength": 1,
      "description": "ChEMBL molecule ID (from chembl_search_molecules), e.g. \"CHEMBL939\" for gefitinib."
    }
  },
  "required": [
    "molecule_chembl_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

chembl_get_assay

Assay provenance behind a bioactivity row: description, type (binding / functional / ADMET / toxicity), the target it measures, organism, and ChEMBL's 1–9 confidence score (9 = direct assay on the protein target, lower = homologous or indirect). Supply assay_chembl_id from a chembl_get_bioactivities row. Call this to judge whether two measurements are comparable before ranking them together.

Parameters1

assay_chembl_id

string

required

ChEMBL assay ID from a bioactivity row's assay_chembl_id, e.g. "CHEMBL674637".

Raw schema

{
  "type": "object",
  "properties": {
    "assay_chembl_id": {
      "type": "string",
      "minLength": 1,
      "description": "ChEMBL assay ID from a bioactivity row's assay_chembl_id, e.g. \"CHEMBL674637\"."
    }
  },
  "required": [
    "assay_chembl_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

chembl_dataframe_query

Run a read-only SQL SELECT over the bioactivity rows chembl_get_bioactivities spilled to a canvas — rank, group, dedupe, and aggregate across the FULL set, not the inline preview. Reference each staged table by the name chembl_get_bioactivities returned — bioactivities for its potency_ranked view, bioactivities_null_potency for null_potency; discover the staged tables and their columns with chembl_dataframe_describe. Compute honest aggregates here (e.g. SELECT molecule_chembl_id, MEDIAN(pchembl_value) AS med FROM bioactivities WHERE standard_type = 'IC50' GROUP BY 1 ORDER BY 2 DESC). Two independent bounds apply, each reported on its own field: truncated is true when the SQL result exceeded the canvas row cap, and rendered_rows says how many of the returned rows the markdown table holds once its character budget is reached (below row_count on a wide or long result). Page past either bound with SQL LIMIT/OFFSET — append e.g. LIMIT 500 OFFSET 500 and re-call; offsets reach rows beyond the canvas row cap. Requires CANVAS_PROVIDER_TYPE=duckdb.

Parameters2

canvas_id	string	required	Canvas ID returned by chembl_get_bioactivities (spilled: true).
sql	string	required	A read-only SELECT against the staged tables. Reference tables by the names chembl_get_bioactivities returned.

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by chembl_get_bioactivities (spilled: true)."
    },
    "sql": {
      "type": "string",
      "description": "A read-only SELECT against the staged tables. Reference tables by the names chembl_get_bioactivities returned."
    }
  },
  "required": [
    "canvas_id",
    "sql"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

chembl_dataframe_describe

List the tables and columns staged on a canvas by chembl_get_bioactivities — inspect before calling chembl_dataframe_query to write correct SQL. Returns each table with its row count, kind (table | view), and column names + types. Requires CANVAS_PROVIDER_TYPE=duckdb.

Parameters1

canvas_id

string

required

Canvas ID returned by chembl_get_bioactivities (spilled: true).

Raw schema

{
  "type": "object",
  "properties": {
    "canvas_id": {
      "type": "string",
      "pattern": "^[A-Za-z0-9_-]{10}$",
      "description": "Canvas ID returned by chembl_get_bioactivities (spilled: true)."
    }
  },
  "required": [
    "canvas_id"
  ],
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "additionalProperties": false
}

README.md20 KBView on GitHub

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

7 Tools (+1 opt-in) • 2 Resources

Version MCP SDK TypeScript Bun

Public Hosted Server: https://chembl.caseyjhand.com/mcp

Overview

Drug-discovery data over 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 protein targets, rank bioactivity measurements, and look up drug mechanisms and indications from any MCP client. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Tool	Description
`chembl_search_molecules`	Find compounds by name / ChEMBL ID / InChIKey, or run a structure search (exact \| similarity \| substructure) from a SMILES.
`chembl_get_bioactivities`	The flagship compound↔target bridge: bioactivity measurements for a molecule, a target, or both (the compound×target pair), ranked on `pchembl_value`, or the measurements without one via `potency_view`. Large sets spill to a canvas.
`chembl_search_targets`	Resolve a protein / gene symbol / UniProt accession to the ChEMBL target ID `chembl_get_bioactivities` needs.
`chembl_get_drug_info`	Drug pharmacology — mechanism(s) of action, molecular target(s), action type, first-approval year, and clinical indications.
`chembl_get_assay`	Assay provenance behind a bioactivity row — type, target, organism, and ChEMBL's 1–9 confidence score.
`chembl_dataframe_query`	Run a read-only SQL `SELECT` over the bioactivity rows spilled to a canvas — rank, group, dedupe, aggregate across the full set.
`chembl_dataframe_describe`	List the tables and columns staged on a canvas, so you can write correct SQL before querying.
`chembl_dataframe_drop`	Drop a named staged table from a canvas. Opt-in via `CHEMBL_DATAFRAME_DROP_ENABLED=true` — absent from `tools/list` when off, since TTL already reclaims staged tables.

Resources

Resource	Description
`chembl://molecule/{chemblId}`	A molecule record by ChEMBL ID — the same shape a `chembl_search_molecules` row carries.
`chembl://target/{chemblId}`	A target record by ChEMBL target ID — preferred name, type, organism, and component UniProt accessions + gene symbols.

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.

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 (name search only) restricts to compounds at or above a max clinical phase
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
Paginated via nextCursor / cursor, omitted (not null) on the last page — redeem a cursor with the same filters that minted it
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
Filter by standard_type (IC50/Ki/EC50/…), pchembl_value_min, assay_type, organism; ranked on pchembl_value — comparable only within one standard_type
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), capped at CHEMBL_MAX_SPILL_ROWS (default 50,000) and reported truncated: true + staged_row_count when hit; requires CANVAS_PROVIDER_TYPE=duckdb
The inline preview is always capped at limit (default 25) regardless of spill status; the optional canvas_id reuses a canvas, but re-querying the same view replaces its prior rows

`chembl_search_targets` _tool

Supply at least one of accession (UniProt, e.g. P00533), gene_symbol, or query (free-text); 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
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
Chain target_chembl_id into chembl_get_bioactivities

`chembl_get_drug_info` _tool

Supply molecule_chembl_id; returns mechanism(s) of action, molecular target(s), action type, first-approval year, and clinical indications with the max phase reached for each
Mechanisms and indications are fetched with Promise.allSettled, so a rejected list degrades to a disclosed partial result rather than failing the call
Each list carries its own mechanisms_status / indications_status (complete / truncated / failed) next to a *_total_count — an empty array is authoritative only when the status is complete
A mechanism's target_chembl_id chains into chembl_get_bioactivities

`chembl_get_assay` _tool

Supply assay_chembl_id from a chembl_get_bioactivities row
Returns description, assay type (binding / functional / ADMET / toxicity), the target measured, organism, and ChEMBL's 1–9 confidence score (9 = direct assay on the protein target, lower = homologous or indirect)
Call it to judge whether two measurements are comparable before ranking them together

`chembl_dataframe_query` _tool

Accepts a single read-only SELECT against a canvas_id from a spilled chembl_get_bioactivities call; 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
Two independent bounds, each disclosed: truncated is the canvas engine's own query-result cap; rendered_rows is how many rows the content[] markdown table holds under its character budget — either can trip without the other; page past both with SQL LIMIT/OFFSET
structuredContent.rows always carries the full materialized result regardless of the render bound
Requires CANVAS_PROVIDER_TYPE=duckdb, else a canvas_disabled error

`chembl_dataframe_describe` _tool

Supply a canvas_id from a spilled chembl_get_bioactivities call
Returns each staged table/view with its row count, kind, and column names + types
Requires CANVAS_PROVIDER_TYPE=duckdb, else a canvas_disabled error

`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 already gone
Rarely needed — per-table and per-canvas TTL already reclaim staged tables; reach for it only to free a large table early in a long session
Requires CANVAS_PROVIDER_TYPE=duckdb

`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)
chemblId is validated against the CHEMBL\d+ pattern
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 validated against the CHEMBL\d+ pattern
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, and spilled tables report truncated + staged_row_count, so a page or slice is never mistaken for the complete set
Typed, recoverable errors — missing_filter / missing_input / contradictory_potency_filter / canvas_disabled carry recovery hints, so callers correct the call without parsing prose
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:

json

{
  "mcpServers": {
    "chembl-mcp-server": {
      "type": "streamable-http",
      "url": "https://chembl.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

ChEMBL is keyless — no API key or account is required.

Add the following to your MCP client configuration file:

json

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

Or with npx (no Bun required):

json

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

Or with Docker:

json

{
  "mcpServers": {
    "chembl-mcp-server": {
      "type": "stdio",
      "command": "docker",
      "args": ["run", "-i", "--rm", "-e", "MCP_TRANSPORT_TYPE=stdio", "ghcr.io/cyanheads/chembl-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

To unlock the analytical SQL path (the bioactivities spill and the chembl_dataframe_* tools), add "CANVAS_PROVIDER_TYPE": "duckdb" to the env.

Prerequisites

Bun v1.4.0 or higher (or Node.js v24+).
Optional: set CANVAS_PROVIDER_TYPE=duckdb to enable the DataCanvas SQL path for large bioactivity sets.

Installation

Clone the repository:

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

Navigate into the directory:

cd chembl-mcp-server

Install dependencies:

bun install

Configure environment:

cp .env.example .env
# edit .env to override any defaults (all optional)

Configuration

All configuration is validated at startup via Zod schemas in src/config/server-config.ts. ChEMBL is keyless, so every variable is optional.

Variable	Description	Default
`CANVAS_PROVIDER_TYPE`	Set to `duckdb` to enable the bioactivity spill and the `chembl_dataframe_*` SQL tools. When `none`, large sets inline a preview but never spill.	`none`
`CHEMBL_API_BASE_URL`	Base URL for the ChEMBL REST data API. Override for a private mirror or pinned host.	`https://www.ebi.ac.uk/chembl/api/data`
`CHEMBL_REQUEST_TIMEOUT_MS`	Per-request timeout in milliseconds for upstream ChEMBL fetches.	`30000`
`CHEMBL_MAX_PAGE_SIZE`	ChEMBL per-page cap when streaming activity pages for the spill (max 1000).	`1000`
`CHEMBL_DEFAULT_LIMIT`	Default result limit applied when callers omit it.	`25`
`CHEMBL_MAX_SPILL_ROWS`	Ceiling on rows `chembl_get_bioactivities` stages to a canvas table, and so on the upstream page drain behind it. Over the cap the response reports `truncated: true`.	`50000`
`CHEMBL_DATAFRAME_DROP_ENABLED`	Register the opt-in `chembl_dataframe_drop` tool (absent from `tools/list` when off).	`false`
`MCP_TRANSPORT_TYPE`	Transport: `stdio` or `http`.	`stdio`
`MCP_HTTP_PORT`	Port for the HTTP server.	`3010`
`MCP_SESSION_MODE`	HTTP session posture; `stateless`, `stateful`, or `auto` (resolves to `stateful`). Overrides the server's stateless declaration.	`stateless`
`MCP_AUTH_MODE`	Auth mode: `none`, `jwt`, or `oauth`.	`none`
`MCP_LOG_LEVEL`	Log level (RFC 5424).	`info`
`LOGS_DIR`	Directory for log files (Node.js only).	`<project-root>/logs`
`LOG_TOOL_FAILURE_PAYLOADS`	Log failed calls' arguments and results with key-name redaction; secrets inside free-form values remain visible.	`false`
`LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTES`	UTF-8 byte cap per logged input/result payload.	`16384`
`OTEL_ENABLED`	Enable OpenTelemetry instrumentation.	`false`
`OTEL_EXPORTER_OTLP_ENDPOINT`	Base URL for traces and metrics, using `/v1/traces` and `/v1/metrics`.	—
`OTEL_EXPORTER_OTLP_LOGS_ENDPOINT`	Explicit full endpoint for OTLP log export. Requires the optional log peers; included in the default Docker build.	—

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, changelog sync
bun run test       # Vitest test suite
bun run lint:mcp   # Validate MCP definitions against spec

Docker

docker build -t chembl-mcp-server .
docker run --rm -e MCP_TRANSPORT_TYPE=stdio chembl-mcp-server

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 CANVAS_PROVIDER_TYPE=duckdb works on either image architecture.

Project structure

Directory	Purpose
`src/index.ts`	`createApp()` entry point — registers tools/resources and inits the ChEMBL service + optional canvas.
`src/config`	Server-specific environment variable parsing and validation with Zod.
`src/mcp-server/tools/definitions`	Tool definitions (`.tool.ts`). Five ChEMBL tools plus the three `chembl_dataframe_` canvas tools.
`src/mcp-server/resources/definitions`	Resource definitions (`*.resource.ts`). Molecule and target record mirrors.
`src/services/chembl`	The single ChEMBL upstream client — URL builder, pagination, numeric coercion, nested-structure flattening, activity page stream.
`src/services/canvas-accessor.ts`	Module-level holder for the optional `DataCanvas` wired in `createApp({ setup })`.
`tests/`	Unit and integration tests mirroring `src/`.

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:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.

Install

Tools (7)

chembl_search_moleculeschembl_get_bioactivitieschembl_search_targetschembl_get_drug_infochembl_get_assaychembl_dataframe_querychembl_dataframe_describe

Configuration

Environment variables

CANVAS_PROVIDER_TYPEdefault none

Set to 'duckdb' to enable the bioactivity DataCanvas spill and the chembl_dataframe_* SQL tools. When 'none', large bioactivity sets inline a preview but never spill.

CHEMBL_API_BASE_URLdefault https://www.ebi.ac.uk/chembl/api/data

Base URL for the ChEMBL REST data API. Override for a private mirror or pinned host.

CHEMBL_REQUEST_TIMEOUT_MSdefault 30000

Per-request timeout in milliseconds for upstream ChEMBL fetches.

CHEMBL_MAX_PAGE_SIZEdefault 1000

ChEMBL per-page cap when streaming activity pages for the bioactivity spill (max 1000).

CHEMBL_DEFAULT_LIMITdefault 25

Default result limit applied when callers omit it.

CHEMBL_MAX_SPILL_ROWSdefault 50000

Ceiling on rows chembl_get_bioactivities stages to a DataCanvas table, and so on the upstream page drain behind it. Over the cap the response reports truncated: true.

CHEMBL_DATAFRAME_DROP_ENABLEDdefault false

Set to 'true' to register the opt-in chembl_dataframe_drop tool (absent from tools/list when off).

MCP_LOG_LEVELdefault info

Sets the minimum log level for output (e.g., 'debug', 'info', 'warn').

MCP_HTTP_HOSTdefault 127.0.0.1

The hostname for the HTTP server.

MCP_HTTP_PORTdefault 3010

The port to run the HTTP server on.

MCP_HTTP_ENDPOINT_PATHdefault /mcp

The endpoint path for the MCP server.

MCP_AUTH_MODEdefault none

Authentication mode to use: 'none', 'jwt', or 'oauth'.

Add to VS Code Add to Cursor

claude_desktop_config.json

json

{
  "mcpServers": {
    "chembl-mcp-server": {
      "command": "npx",
      "args": [
        "-y",
        "@cyanheads/chembl-mcp-server@0.3.2",
        "run",
        "start:stdio"
      ],
      "env": {
        "CANVAS_PROVIDER_TYPE": "none",
        "CHEMBL_API_BASE_URL": "https://www.ebi.ac.uk/chembl/api/data",
        "CHEMBL_REQUEST_TIMEOUT_MS": "30000",
        "CHEMBL_MAX_PAGE_SIZE": "1000",
        "CHEMBL_DEFAULT_LIMIT": "25",
        "CHEMBL_MAX_SPILL_ROWS": "50000",
        "CHEMBL_DATAFRAME_DROP_ENABLED": "false",
        "MCP_LOG_LEVEL": "info"
      }
    }
  }
}

@cyanheads/chembl-mcp-server (MCP)

🛠️ Key Features

🚀 Use Cases

⚡ Developer Benefits

⚠️ Limitations

Topics

chembl_search_molecules

chembl_get_bioactivities

chembl_search_targets

chembl_get_drug_info

chembl_get_assay

chembl_dataframe_query

chembl_dataframe_describe

@cyanheads/chembl-mcp-server

Overview

Tools

Resources

Capability reference

chembl_search_molecules tool

chembl_get_bioactivities tool

chembl_search_targets tool

chembl_get_drug_info tool

chembl_get_assay tool

chembl_dataframe_query tool

chembl_dataframe_describe tool

chembl_dataframe_drop tool

chembl://molecule/{chemblId} resource

chembl://target/{chemblId} resource

Features

Getting started

Public Hosted Instance

Self-Hosted / Local

Prerequisites

Installation

Configuration

Running the server

Local development

Docker

Project structure

Development guide

Contributing

License

Install

Configuration

Related servers

`chembl_search_molecules` _tool

`chembl_get_bioactivities` _tool

`chembl_search_targets` _tool

`chembl_get_drug_info` _tool

`chembl_get_assay` _tool

`chembl_dataframe_query` _tool

`chembl_dataframe_describe` _tool

`chembl_dataframe_drop` _tool

`chembl://molecule/{chemblId}` _resource

`chembl://target/{chemblId}` _resource