# chembl-mcp-server [Health: Active]
**Category:** 🧬 Biology & Bioinformatics
**Repository:** https://github.com/cyanheads/chembl-mcp-server
**GitHub Stars:** 1
**Views:** 0
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/chembl-mcp-server
## Description
Link compounds to protein targets, rank bioactivity, and look up drug mechanisms and indications.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `bunx` (confidence: high):
```json
"mcpServers": {
"chembl-mcp-server": {
"command": "bunx",
"args": ["@cyanheads/chembl-mcp-server@latest"]
}
}
```
## Documentation & 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.
7 Tools (+1 opt-in) • 2 Resources
[](./CHANGELOG.md) [](./LICENSE) [](https://github.com/users/cyanheads/packages/container/package/chembl-mcp-server) [](https://modelcontextprotocol.io/) [](https://www.npmjs.com/package/@cyanheads/chembl-mcp-server) [](https://www.typescriptlang.org/) [](https://bun.sh/)
[](https://github.com/cyanheads/chembl-mcp-server/releases/latest/download/chembl-mcp-server.mcpb) [](https://cursor.com/en/install-mcp?name=chembl-mcp-server&config=eyJjb21tYW5kIjoibnB4IiwiYXJncyI6WyIteSIsIkBjeWFuaGVhZHMvY2hlbWJsLW1jcC1zZXJ2ZXIiXX0=) [](https://vscode.dev/redirect?url=vscode:mcp/install?%7B%22name%22%3A%22chembl-mcp-server%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%22%2C%22%40cyanheads%2Fchembl-mcp-server%22%5D%7D)
[](https://www.npmjs.com/package/@cyanheads/mcp-ts-core)
**Public Hosted Server:** [https://chembl.caseyjhand.com/mcp](https://chembl.caseyjhand.com/mcp)
---
## 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):
| Tool | Description |
|:---|:---|
| `chembl_search_molecules` | Find compounds by name / ChEMBL ID / InChIKey, or run a structure search (exact \| similarity \| substructure) from a SMILES. |
| `chembl_get_bioactivities` | The flagship compound↔target bridge: bioactivity measurements for a molecule, a target, or **both** (the compound×target pair), ranked on `pchembl_value`, or the measurements without one via `potency_view`. Large sets spill to a canvas. |
| `chembl_search_targets` | Resolve a protein / gene symbol / UniProt accession to the ChEMBL target ID `chembl_get_bioactivities` needs. |
| `chembl_get_drug_info` | Drug pharmacology — mechanism(s) of action, molecular target(s), action type, first-approval year, and clinical indications. |
| `chembl_get_assay` | Assay provenance behind a bioactivity row — type, target, organism, and ChEMBL's 1–9 confidence score. |
| `chembl_dataframe_query` | Run a read-only SQL `SELECT` over the bioactivity rows spilled to a canvas — rank, group, dedupe, aggregate across the full set. |
| `chembl_dataframe_describe` | List the tables and columns staged on a canvas, so you can write correct SQL before querying. |
| `chembl_dataframe_drop` | Drop a named staged table from a canvas. Opt-in via `CHEMBL_DATAFRAME_DROP_ENABLED=true` — absent from `tools/list` when off, since TTL already reclaims staged tables. |
### `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
| Type | Name | Description |
|:---|:---|:---|
| Resource | `chembl://molecule/{chemblId}` | A molecule record by ChEMBL ID — the same shape a `chembl_search_molecules` row carries (ID, names, structures, properties, max clinical phase). |
| Resource | `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 — 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`](https://www.npmjs.com/package/@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:
```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
```
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](https://bun.sh/) 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:**
```sh
git clone https://github.com/cyanheads/chembl-mcp-server.git
```
2. **Navigate into the directory:**
```sh
cd chembl-mcp-server
```
3. **Install dependencies:**
```sh
bun install
```
4. **Configure environment:**
```sh
cp .env.example .env
# edit .env to override any defaults (all optional)
```
## Configuration
All configuration is validated at startup via Zod schemas in `src/config/server-config.ts`. ChEMBL is keyless, so every variable is optional.
| Variable | Description | Default |
|:---|:---|:---|
| `CANVAS_PROVIDER_TYPE` | Set to `duckdb` to enable the bioactivity spill and the `chembl_dataframe_*` SQL tools. When `none`, large sets inline a preview but never spill. | `none` |
| `CHEMBL_API_BASE_URL` | Base URL for the ChEMBL REST data API. Override for a private mirror or pinned host. | `https://www.ebi.ac.uk/chembl/api/data` |
| `CHEMBL_REQUEST_TIMEOUT_MS` | Per-request timeout in milliseconds for upstream ChEMBL fetches. | `30000` |
| `CHEMBL_MAX_PAGE_SIZE` | ChEMBL per-page cap when streaming activity pages for the spill (max 1000). | `1000` |
| `CHEMBL_DEFAULT_LIMIT` | Default result limit applied when callers omit it. | `25` |
| `CHEMBL_MAX_SPILL_ROWS` | Ceiling on rows `chembl_get_bioactivities` stages to a canvas table, and so on the upstream page drain behind it. Over the cap the response reports `truncated: true`. | `50000` |
| `CHEMBL_DATAFRAME_DROP_ENABLED` | Register the opt-in `chembl_dataframe_drop` tool (absent from `tools/list` when off). | `false` |
| `MCP_TRANSPORT_TYPE` | Transport: `stdio` or `http`. | `stdio` |
| `MCP_HTTP_PORT` | Port for the HTTP server. | `3010` |
| `MCP_AUTH_MODE` | Auth mode: `none`, `jwt`, or `oauth`. | `none` |
| `MCP_LOG_LEVEL` | Log level (RFC 5424). | `info` |
| `LOGS_DIR` | Directory for log files (Node.js only). | `/logs` |
| `OTEL_ENABLED` | Enable [OpenTelemetry instrumentation](https://github.com/cyanheads/mcp-ts-core/tree/main/docs/telemetry). | `false` |
See [`.env.example`](https://github.com/cyanheads/chembl-mcp-server/blob/HEAD/.env.example) for the full list of optional overrides.
## Running the server
### Local development
- **Build and run:**
```sh
# One-time build
bun run rebuild
# Run the built server
bun run start:stdio
# or
bun run start:http
```
- **Run checks and tests:**
```sh
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
```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. The fully-resolved `@duckdb` native binary is copied from the build stage so `CANVAS_PROVIDER_TYPE=duckdb` works at runtime.
## Project structure
| Directory | Purpose |
|:---|:---|
| `src/index.ts` | `createApp()` entry point — registers tools/resources and inits the ChEMBL service + optional canvas. |
| `src/config` | Server-specific environment variable parsing and validation with Zod. |
| `src/mcp-server/tools/definitions` | Tool definitions (`*.tool.ts`). Five ChEMBL tools plus the three `chembl_dataframe_*` canvas tools. |
| `src/mcp-server/resources/definitions` | Resource definitions (`*.resource.ts`). Molecule and target record mirrors. |
| `src/services/chembl` | The single ChEMBL upstream client — URL builder, pagination, numeric coercion, nested-structure flattening, activity page stream. |
| `src/services/canvas-accessor.ts` | Module-level holder for the optional `DataCanvas` wired in `createApp({ setup })`. |
| `tests/` | Unit and integration tests mirroring `src/`. |
## Development guide
See [`CLAUDE.md`/`AGENTS.md`](https://github.com/cyanheads/chembl-mcp-server/blob/HEAD/CLAUDE.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:
```sh
bun run devcheck
bun run test
```
## License
Apache-2.0 — see [LICENSE](https://github.com/cyanheads/chembl-mcp-server/blob/HEAD/LICENSE) for details.