Chembl Mcp Server

io.github.cyanheads由 GitHub 帳號 cyanheads 發布v0.6.0更新於 Nov 11, 2026

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

已驗證Streamable HTTP可網頁執行資料庫資料與分析AI 與機器學習

概覽

AI 產生的概覽

查詢 ChEMBL 藥物研發資料:尋找化合物與蛋白質標靶、排序生物活性測量值,並查詢藥物作用機制與適應症。

可以做什麼
  • 依名稱、ChEMBL ID、InChIKey 或 SMILES 結構(精確、相似、子結構)搜尋化合物,並以 UniProt 登錄號、基因符號或名稱解析標靶
  • 取得某個分子、某個標靶或化合物-標靶配對的生物活性測量值,可依標準類型、效價、實驗類型、物種與變異體篩選
  • 查詢藥物藥理資訊:作用機制、作用標靶、作用類型、最高臨床階段、首次核准年份、撤市與黑框警告紀錄以及適應症
  • 檢視實驗來源,以及測量值背後的論文、專利或資料集,含 PubMed ID 與 DOI
  • 將大量生物活性資料暫存到畫布,檢視暫存表結構,並以唯讀 SQL 進行排序、分組與彙總
適用情境
適合需要把化合物與蛋白質標靶連結、為某個標靶尋找高活性先導化合物、確認藥物機制、核准狀態或警告,或把測量值追溯到實驗與原始文獻的情境。
執行需求
可使用遠端 Streamable HTTP 端點,或透過 npx、bunx、Docker 在本機執行(需 Bun 1.4.4+ 或 Node.js v24+)。ChEMBL 不需金鑰,不需要帳號或 API key,所有環境變數皆為選用。SQL 畫布預設使用 DuckDB,可用 CANVAS_PROVIDER_TYPE=none 關閉。需要能連線至 ChEMBL API 的網路。
安裝前請注意
chembl_dataframe_drop 工具僅在 CHEMBL_DATAFRAME_DROP_ENABLED=true 時註冊,會刪除暫存表;SQL 僅限唯讀 SELECT。大量資料集可能因列數上限或時間預算而被截斷,預覽結果並非完整集合。資料來自 ChEMBL,採 CC BY-SA 3.0 授權,下游使用須標示來源。設定 CHEMBL_API_BASE_URL 會把請求導向其他主機。

安裝

在 SourceWeft 中

  1. 開啟 儀表板中的 Chembl Mcp Server,將其新增到工作區。
  2. 為需要使用其工具的對話啟用該服務。

Web executable,透過 Streamable HTTP。 遠端服務在工作區中設定後即可從網頁執行環境執行。

交給代理程式安裝

把這段提示詞貼上到 Claude Code、Codex、Cursor 等代理程式,或 SourceWeft 對話中。代理程式會讀取該伺服器的安裝指南,先向你展示發布者、端點和登入方式,經你同意後再把它新增到你的客戶端。金鑰不會寫進任何命令。

閱讀 https://sourceweft.com/mcp/io.github.cyanheads%2Fchembl-mcp-server/install.md,並按其中說明把這個 MCP 伺服器接入我的客戶端。修改任何設定之前,先告訴我它的發布者、端點和登入方式,等我確認。不要把 API 金鑰寫進命令或我會提交的檔案;問我金鑰應從哪裡取得。

檢視代理程式所依據的安裝指南

其他 MCP 客戶端

把它新增到你客戶端的 mcpServers 設定中。

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

README

@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

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


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

ToolDescription
chembl_search_moleculesFind compounds by name / ChEMBL ID / InChIKey, or run a structure search (exact | similarity | substructure) from a SMILES.
chembl_get_bioactivitiesThe flagship compound↔target bridge: bioactivity measurements for a molecule (or its whole family of forms), 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_targetsResolve a protein / gene symbol / UniProt accession to the ChEMBL target ID chembl_get_bioactivities needs.
chembl_get_drug_infoDrug pharmacology — mechanism(s) of action, molecular target(s), action type, withdrawal and boxed-warning status with ChEMBL's warning records, and clinical indications across the drug's salts and other alternate forms, beside the queried form's own max phase and first-approval year.
chembl_get_assayAssay provenance behind bioactivity rows, for one assay or a shortlist — type, target, organism, and ChEMBL's 0–9 confidence score.
chembl_get_documentsThe publication, patent, or deposited dataset behind a bioactivity row's or assay's document_chembl_id, for one document or a shortlist — title, authors, journal, year, PubMed ID, and DOI to cite.
chembl_dataframe_queryRun a read-only SQL SELECT over the bioactivity rows staged on a canvas — rank, group, dedupe, aggregate across the full set.
chembl_dataframe_describeList the tables and columns staged on a canvas, so you can write correct SQL before querying.
chembl_dataframe_dropDrop 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

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

Skills

SkillDescription
chembl-guideGates and workflows for the chembl_* tools: pinning a protein to its single-protein target, ranking leads without mixing mutants or salts, reading selectivity with the inactive results, and checking assay provenance and approval status. Served as skill://chembl-guide/SKILL.md; also ships in plugin installs, the .mcpb bundle, the npm package, and the Docker image.

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:

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:

sh
MCP_TRANSPORT_TYPE=http MCP_HTTP_PORT=3010 bun run start:http# Server listens at http://localhost:3010/mcp

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

  1. Clone the repository:
sh
git clone https://github.com/cyanheads/chembl-mcp-server.git
  1. Navigate into the directory:
sh
cd chembl-mcp-server
  1. Install dependencies:
sh
bun install
  1. Configure environment:
sh
cp .env.example .env# edit .env to override any defaults (all optional)

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.

VariableDescriptionDefault
CANVAS_PROVIDER_TYPEDataCanvas provider for the bioactivity spill and the chembl_dataframe_* SQL tools. Set to none to disable it: large sets then inline a preview but never spill.duckdb
CHEMBL_API_BASE_URLBase 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_MSPer-attempt timeout in milliseconds for an upstream ChEMBL request, capped by what is left of the call's time budget (45 s for most calls, CHEMBL_SPILL_DEADLINE_MS for a bioactivity spill).30000
CHEMBL_MAX_PAGE_SIZERows per upstream ChEMBL page (max 1000). The bioactivity spill walks pages of this size; an inline bioactivity page requests its limit, capped at this size.1000
CHEMBL_DEFAULT_LIMITDefault result limit applied when callers omit it.25
CHEMBL_MAX_SPILL_ROWSCeiling on rows chembl_get_bioactivities stages to a canvas table, and so on the upstream page walk behind it. Over the cap the response reports truncated: true and truncated_by: "row_cap".50000
CHEMBL_MAX_CONCURRENT_PAGESMost chembl_get_bioactivities spill-page requests in flight at once (1–6), shared by every call on the server.4
CHEMBL_SPILL_DEADLINE_MSTime budget in milliseconds for one chembl_get_bioactivities spill, its count and page walk (10000–600000). At expiry the rows fetched so far stage with truncated: true and truncated_by: "time_budget".45000
CHEMBL_DATAFRAME_DROP_ENABLEDRegister the opt-in chembl_dataframe_drop tool (absent from tools/list when off).false
MCP_TRANSPORT_TYPETransport: stdio or http.stdio
MCP_HTTP_PORTPort for the HTTP server.3010
MCP_SESSION_MODEHTTP session posture; stateless, stateful, or auto (resolves to stateful). Overrides the server's stateless declaration.stateless
MCP_AUTH_MODEAuth mode: none, jwt, or oauth.none
MCP_LOG_LEVELLog level (RFC 5424).debug (the Docker image sets info)
LOGS_DIRDirectory for log files (Node.js only).<project-root>/logs
LOG_TOOL_FAILURE_PAYLOADSLog failed calls' arguments and results with key-name redaction; secrets inside free-form values remain visible.false
LOG_TOOL_FAILURE_PAYLOAD_MAX_BYTESUTF-8 byte cap per logged input/result payload.16384
OTEL_ENABLEDEnable OpenTelemetry instrumentation.false
OTEL_EXPORTER_OTLP_ENDPOINTBase URL for traces and metrics, using /v1/traces and /v1/metrics.—
OTEL_EXPORTER_OTLP_LOGS_ENDPOINTExplicit 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.

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:

    sh
    # One-time buildbun run rebuild
    # Run the built serverbun run start:stdio# orbun run start:http
  • Run checks and tests:

    sh
    bun run devcheck   # Lint, format, typecheck, security, changelog syncbun run test       # Vitest test suitebun run lint:mcp   # Validate MCP definitions against spec

Docker

sh
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 the default DuckDB canvas works on either image architecture.

Project structure

DirectoryPurpose
src/index.tscreateApp() entry point — registers tools/resources, serves skills/, and inits the ChEMBL service + the DataCanvas, which it defaults to DuckDB.
src/configServer-specific environment variable parsing and validation with Zod.
src/mcp-server/input-normalization.tsInput-edge parsing shared by the tools and resources — ChEMBL IDs and ID lists, molecule references, assay_type, uppercase codes, the optional canvas_id, the limit clamp.
src/mcp-server/markdown-text.tsThe escape every upstream string passes through in format(), so content[] reads back the field exactly.
src/mcp-server/tools/definitionsTool definitions (*.tool.ts). Six ChEMBL tools plus the three chembl_dataframe_* canvas tools.
src/mcp-server/resources/definitionsResource definitions (*.resource.ts). Molecule and target record mirrors.
src/services/chemblThe single ChEMBL upstream client — URL builder, pagination, numeric coercion, nested-structure flattening, activity page stream.
src/services/canvas-accessor.tsModule-level holder for the optional DataCanvas wired in createApp({ setup }).
skills/Agent skills the server publishes (chembl-guide).
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:

sh
bun run devcheckbun run test

License

Apache-2.0 — see LICENSE for details.

來源:README.md,提交 95ed766

工具

8

chembl_search_molecules

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, max clinical phase, and the family parent_chembl_id 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 salt often ranks ahead of its parent and carries a small share of the family's measurements, so check parent_chembl_id before chaining. A capped result carries nextCursor — pass it back as cursor with the same filters to read the next page.

輸入參數limitquerycursorstructuresearch_typemax_phase_minsimilarity_threshold

chembl_get_bioactivities

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. A drug's measurements are often split across its salts and other alternate forms, so molecule_chembl_id reads that one form unless include_alternate_forms widens it to the whole family under its parent (a salt's ID included), every view, page, and spill reading the same family. Filter by standard_type (IC50/Ki/EC50/…), minimum potency pchembl_value_min, assay_type, organism, and variant (wild type, or one recorded mutant such as "T315I"). Each row carries its activity_comment and data_validity_comment, its assay variant, its source document for citation, its family parent_molecule_chembl_id (merge a drug with its salts on it), ChEMBL's potential_duplicate flag for repeat citations, and its assay format (bao_label). 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

輸入參數limitcursorvariantorganismcanvas_idassay_typepotency_viewstandard_typetarget_chembl_idpchembl_value_minmolecule_chembl_idinclude_alternate_forms

chembl_search_targets

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, or a ChEMBL target ID such as CHEMBL203 to read that one target); 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.

輸入參數limitquerycursororganismaccessiongene_symboltarget_type

chembl_get_drug_info

chembl-get-drug-info

Pharmacology for a drug (molecule): mechanism(s) of action, the molecular target(s) it acts on, action type (inhibitor / agonist / …), max clinical phase, first-approval year, whether it has been withdrawn from a market or carries a boxed warning with ChEMBL's withdrawal and boxed-warning records, and clinical indications with the max phase reached for each. A withdrawn drug keeps max_phase 4 — read withdrawn and warnings before taking phase 4 as on the market. Supply molecule_chembl_id (from chembl_search_molecules) — a parent or any of its salts and other alternate forms reads the same family: ChEMBL often records a drug's mechanisms, approved indications, and warnings on a salt, so both flags and every list cover the whole family under parent_molecule_chembl_id, isotope-labelled and deuterated analogs included. max_phase and first_approval come from the queried form's own record, never from the family, since an analog filed under an approved parent can itself be investigational; re-call with parent_molecule_chembl_id to read them for the parent. Each mechanism and warning names the form it is recorded on, and each indication is listed once per MeSH/EFO pair at the highest phase any form reached, with the forms it is recorded on, each at its own phase. 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, indications, or warnings array means the molecule has none recorded only when the matching mechanisms_status / indications_status / warnings_status is "complete" — "failed" means the list was not retrieved (the request ran out of time or ChEMBL answered with an error, as the matching *_failure says) and the array says nothing about the molecule, and "truncated" means the page cap fetched fewer rows than ChEMBL holds, which the matching

輸入參數molecule_chembl_id必填

chembl_get_assay

chembl-get-assay

Assay provenance behind bioactivity rows, for one assay or a shortlist in one call: description, type (binding / functional / ADMET / toxicity), BioAssay Ontology format (single protein, cell-based, organism-based, …), the target it measures, organism, cell type, tissue, strain, source document, and ChEMBL's 0–9 confidence score (9 = direct single protein target, lower = homologous, complex, or non-protein targets, 0 = no target assigned yet). Supply assay_chembl_ids from chembl_get_bioactivities rows: the first 100 distinct IDs are looked up and returned in the order given, the rest come back in deferred_ids to pass again, and an ID with no assay record (a compound or target ID included) is listed in not_found_ids rather than failing the call. Call this to judge whether measurements are comparable before ranking them together.

輸入參數assay_chembl_ids必填

chembl_get_documents

chembl-get-documents

The publication, patent, or deposited dataset behind ChEMBL document IDs, for one document or a shortlist in one call: type, title, authors, journal, year, volume, issue, pages, PubMed ID, DOI, and patent number. Supply document_chembl_ids from the document_chembl_id of chembl_get_bioactivities rows or chembl_get_assay records: the first 100 distinct IDs are looked up and returned in the order given, the rest come back in deferred_ids to pass again, and an ID with no document record (a compound, target, or assay ID included) is listed in not_found_ids rather than failing the call. Call this to cite a measurement; a pubmed_id or doi chains to a PubMed or Crossref server for the abstract.

輸入參數document_chembl_ids必填

chembl_dataframe_query

chembl-dataframe-query

Run a read-only SQL SELECT over the bioactivity rows chembl_get_bioactivities staged on 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 parent_molecule_chembl_id, MEDIAN(pchembl_value) AS med FROM bioactivities WHERE standard_type = 'IC50' AND potential_duplicate IS NOT TRUE GROUP BY 1 ORDER BY 2 DESC, which merges a drug with its salts and drops likely repeat citations). Every row the SQL returns comes back on both structuredContent and content[], so bound the result in the SQL itself: project only the columns you need and set a LIMIT. truncated is true when the result exceeded the canvas row cap; 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 already has — offsets reach rows beyond the cap. Unavailable when the server sets CANVAS_PROVIDER_TYPE=none.

輸入參數sql必填canvas_id必填

chembl_dataframe_describe

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. Unavailable when the server sets CANVAS_PROVIDER_TYPE=none.

輸入參數canvas_id必填

版本歷史

8
  1. v0.6.0最新Nov 11, 2026
  2. v0.5.0Oct 29, 2026
  3. v0.4.1Oct 25, 2026
  4. v0.4.0Oct 18, 2026
  5. v0.3.3Oct 11, 2026
  6. v0.3.2Sep 27, 2026
  7. v0.3.0Sep 20, 2026
  8. v0.2.4Sep 16, 2026

評分

已滿足適用檢查項的 100%

該評分衡量此收錄條目的完整程度,依據註冊中心條目、端點與公開來源計算得出。它不是對伺服器本身的評價,也不表示伺服器安全或目前可用:可連通性是帶日期的檢查結果,評分也不包含安裝量或使用者評價。

  • 近 30 天內可連通必需25 分
  • 已宣告認證方式必需10 分
  • 已列出工具必需15 分
  • 描述必需15 分
  • 圖示10 分
  • 文件15 分
  • 授權條款10 分