Tools

Eight tools — five for the ChEMBL compound/target/bioactivity surface, plus three for SQL analytics over the DuckDB-backed canvas that chembl_get_bioactivities spills to (the third is opt-in):

chembl_search_molecules

The discovery entry point for compounds.

• Default search_type=name matches drug names, synonyms, ChEMBL IDs, and InChIKeys in one query
• A query that is exactly a ChEMBL ID or an InChIKey is routed to ChEMBL's single-record lookup rather than the fuzzy text index, so it returns totalCount: 1 instead of a full-text relevance count. Adding max_phase_min returns the query to the text index, since that filter belongs to the search endpoint
• Structure search via search_type: exact (exact match), similarity (Tanimoto ≥ threshold), or substructure (contains the query structure) — supply structure as a SMILES
• similarity_threshold is an integer 40–100 (default 70; ChEMBL rejects values below 40)
• max_phase_min restricts name searches to compounds at or above a max clinical phase (e.g. 4 for marketed drugs only)
• Every row carries max_phase — the cheap druggability signal (4 = marketed, 0 = research) — plus MW, AlogP, Lipinski rule-of-five violations, and QED. Only search_type=similarity carries a Tanimoto similarity percent; exact and substructure results omit the field entirely, because ChEMBL supplies a score for similarity search alone
• Results past limit are reachable: when more remain, the response carries a nextCursor, and passing it back as cursor returns the following page. It is 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

The flagship tool and the reason the server exists — the curated compound↔target↔assay link.

• Supply at least one of molecule_chembl_id (target deconvolution / selectivity) or target_chembl_id (lead finding); supplying both narrows to that compound–target pair — "how potently does this compound hit this target, and in which assays?" — while neither is a missing_filter error
• Filter by standard_type (IC50 / Ki / EC50 / …), minimum potency pchembl_value_min, assay_type, and organism; rows are ranked on pchembl_value (−log10 molar potency)
• Ranking trap: pchembl_value is comparable only within one standard_type — set the filter, because mixing IC50 and Ki is a scientific error
• Coverage trap: many measurements have no derivable pchembl_value (non-standard types, censored relations) and are absent from the ranked view — aspirin CHEMBL25 has 4,087 measurements but only 158 with a pchembl_value. potency_view picks the side you get: potency_ranked (default) or null_potency for exactly the excluded rows. totalCount spans both either way. The two are separate calls, not one merged stream, because ChEMBL sorts null-potency rows first under a descending potency sort
• Numerics are coerced from upstream JSON strings to number | null at the service boundary — a missing potency reads as null, never 0
• A popular target carries tens of thousands of measurements: when the set exceeds the inline preview it spills to a DataCanvas table — call chembl_dataframe_describe for its columns, then chembl_dataframe_query for honest aggregates across the staged set — while the 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 (default 50,000), which also bounds the upstream page walk behind it. When the cap is hit, truncated: true and staged_row_count say so on both response surfaces — the table is a bounded slice, not the complete view; narrow with standard_type / pchembl_value_min to fit
• The inline rows are always capped at limit (default 25) — spilled, fit inline, or canvas off — so compare that count 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
• The optional canvas_id reuses an existing canvas, but a view's table is always re-registered — a second query of the same view replaces its prior rows rather than appending; omit canvas_id to mint a fresh one

chembl_search_targets

Resolve a protein into the ChEMBL target ID downstream tools need.

• Supply at least one of accession (UniProt, e.g. P00533), gene_symbol (e.g. EGFR), or query (free-text name); narrow further with organism and target_type
• A UniProt accession is the most precise input — chain it from a uniprot / protein server
• Each row carries the target type, organism, and component UniProt accessions + gene symbols (flattened from ChEMBL's nested component synonyms)
• Results past limit are reachable the same way chembl_search_molecules does it — a nextCursor when more remain, passed back as cursor, omitted on the last page
• Chain target_chembl_id into chembl_get_bioactivities

chembl_get_drug_info

Drug pharmacology for a molecule — distinct from the openfda server's label / adverse-event view.

• Supply molecule_chembl_id (from chembl_search_molecules)
• Returns mechanism(s) of action, the molecular target(s), action type (inhibitor / agonist / …), first-approval year, and clinical indications with the max phase reached for each
• Composed from molecule + mechanisms + indications with Promise.allSettled, so a rejected mechanism or indication list degrades to a disclosed partial result rather than failing the call
• Each list carries its own retrieval state — mechanisms_status / indications_status (complete / truncated / failed) next to mechanisms_total_count / indications_total_count, so an empty array is authoritative only when the status is complete
• A mechanism's target_chembl_id chains into chembl_get_bioactivities for compounds hitting the same target

chembl_get_assay

Assay provenance behind a bioactivity row — call it to judge whether two measurements are comparable before ranking them together.

• Supply assay_chembl_id from a chembl_get_bioactivities row
• Returns the description, assay 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)

chembl_dataframe_query / chembl_dataframe_describe / chembl_dataframe_drop

In-conversation SQL analytics over the bioactivity tables that chembl_get_bioactivities spills to a DuckDB-backed canvas. When a query spills, the tool returns a canvas_id and the table_name it staged; pass the canvas ID to chembl_dataframe_query for ranking, grouping, deduplication, and aggregation across the full set — standard DuckDB SQL.

• Read-only. chembl_dataframe_query accepts a single SELECT; 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 for the potency_ranked view, bioactivities_null_potency for null_potency), and discover its columns with chembl_dataframe_describe first.
• Each spilled table holds the full Activity row — the same 18 columns including the normalized standard_* / pchembl_value fields (rank on these) and the raw upstream type / value / units / relation (audit only). Compute aggregates here, never over the inline preview.
• Two independent bounds, both disclosed. truncated means the canvas engine's own query-result cap was hit. rendered_rows reports how many rows the markdown table in content[] actually carried — that table is bounded by a character budget rather than a row count, so wide and narrow rows differ several-fold at the same byte cost. Either bound can trip without the other. structuredContent.rows always carries the full materialized result; to reach rows past either bound, page with SQL LIMIT / OFFSET.
• chembl_dataframe_drop is the only destructive tool and is opt-in (CHEMBL_DATAFRAME_DROP_ENABLED=true) — absent from tools/list when off, because per-table and per-canvas TTL already reclaim staged tables. It still appears in the server manifest and landing page while off, carrying the flag needed to enable it. Reach for it only to free a large table early in a long session.
• All three require CANVAS_PROVIDER_TYPE=duckdb; without it they return a canvas_disabled error and chembl_get_bioactivities degrades to a preview-only response.

Resources and prompts

All resource data is also reachable via the tools, so tool-only MCP clients lose nothing — the resources are convenience injectable-context mirrors of the per-record fetch. {chemblId} is validated against the CHEMBL\d+ pattern. 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.

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool and resource definitions — single file per primitive, framework handles registration and validation
• Unified error handling — handlers throw, framework catches, classifies, and formats
• Typed error contracts with recovery hints (missing_filter, missing_input, canvas_disabled)
• Pluggable auth (none, jwt, oauth) and swappable storage backends
• Structured logging with optional OpenTelemetry tracing
• STDIO and Streamable HTTP transports

ChEMBL-specific:

• Single keyless upstream client for the ChEMBL REST data API — Django-style filtered URL builder, page_meta pagination, withRetry-wrapped fetch + parse
• String → number | null numeric coercion at the service boundary (a missing potency becomes null, never 0 — the scientific-data fidelity rule)
• Bidirectional bioactivity: 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
• DataCanvas spill on the flagship: 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

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 search results report shown / cap / totalCount so a page is never mistaken for the complete set
• Typed, recoverable errors — missing_filter / missing_input / 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:

{
  "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:

{
  "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):

{
  "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:

{
  "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.3.0 or higher (or Node.js v24+).
• Optional: set CANVAS_PROVIDER_TYPE=duckdb to enable the DataCanvas SQL path for large bioactivity sets.

Installation

1. Clone the repository:

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

2. Navigate into the directory:

cd chembl-mcp-server

3. Install dependencies:

bun install

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

See .env.example for the full list of optional overrides.

Running the server

Local development

• Build and run:

  sh

  Copy

  # One-time build
  bun run rebuild
  
  # Run the built server
  bun run start:stdio
  # or
  bun run start:http
  

• Run checks and tests:

  sh

  Copy

  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. The fully-resolved @duckdb native binary is copied from the build stage so CANVAS_PROVIDER_TYPE=duckdb works at runtime.

Project structure

Development guide

See CLAUDE.md/AGENTS.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging, ctx.state for tenant-scoped storage
• Register new tools and resources in the createApp() arrays
• Wrap the ChEMBL API: validate raw → normalize to the flat domain type → return the output schema; never fabricate missing fields (absent numerics become null, never 0)

Contributing

Issues and pull requests are welcome. Run checks and tests before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.