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 分