chembl-mcp-server

chembl-search-molecules

chembl_search_molecules

Read-onlyIdempotent

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.

Input Schema

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

Output Schema

Name	Required	Description
`cap`	No	The limit that was applied.
`error`	No	Present when the call failed. Absent on success.
`shown`	No	Number of molecules returned.
`notice`	No	Guidance when nothing matched — echoes the query and suggests how to broaden — the disclosure that a limit above the maximum was served at the maximum, and, when totalCountCapped is true, that the total is ChEMBL's search ceiling and how to narrow below it.
`molecules`	No	Matching compounds (up to the limit).
`truncated`	No	True when the result was capped at the limit.
`nextCursor`	No	Opaque token for the next page — pass it back as cursor with the same filters. Absent when this page is the last one.
`totalCount`	No	Total compounds matching before the limit was applied — a lower bound when totalCountCapped is true.
`totalCountCapped`	No	True when totalCount is ChEMBL's ceiling for the search — 10000 for a name search, 30000 for a substructure search: at least that many compounds match, and no page past the ceiling can be reached. Narrow the query to bring the matches under it.

Schema Changelog

Changes observed during successful MCP inspections.

Changed1 schema field changedOct 29, 2026

changedOutput schema / properties / molecules / items / properties / max_phase / description

Previous value: -"Max clinical phase: 4 = marketed drug, 0 = research compound. Null when unknown. The cheap druggability signal."New value: +"Max clinical phase: 4 = approved, 3–1 = clinical trial phase, 0.5 = early phase 1, −1 = clinical with the phase unknown. Null when ChEMBL records no clinical development (a preclinical or research compound). The cheap druggability signal."

Changed10 schema fields changedOct 24, 2026

changedInput schema / properties / limit / description

Previous value: -"Maximum molecules to return. Defaults to the server default (25) when omitted."New value: +"Maximum molecules to return, up to 100 — a larger value is served at 100, with a notice saying so. Defaults to the server default (25) when omitted."

changedInput schema / properties / limit / maximum
```
Previous value: -100New value: +10000
```

changedOutput schema / anyOf

Previous value: -[
-  {
-    "not": {
-      "required": [
-        "error"
-      ]
-    },
-    "required": [
-      "molecules",
-      "totalCount",
-      "truncated",
-      "shown",
-      "cap"
-    ]
-  },
-  {
-    "required": [
-      "error"
-    ]
-  }
-]New value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "molecules",
+      "totalCount",
+      "totalCountCapped",
+      "truncated",
+      "shown",
+      "cap"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `missing_input`: Neither query nor structure was supplied, or a structure search_type was chosen without a structure. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `invalid_structure`: ChEMBL could not parse the SMILES of a similarity or substructure search. `missing_input`: Neither query nor structure was supplied, or a structure search_type was chosen without a structure. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "not_found",
-  "rate_limited",
-  "missing_input"
-]New value: +[
+  "not_found",
+  "rate_limited",
+  "invalid_structure",
+  "missing_input"
+]

addedOutput schema / properties / molecules / items / properties / parent_chembl_id

Added value: +{
+  "description": "The parent of the compound's family, e.g. \"CHEMBL553\" for erlotinib hydrochloride — the compound's own ID when it is the parent or ChEMBL records no hierarchy for it. A salt's measurements are a small share of its family's: pass the parent to chembl_get_drug_info, or set include_alternate_forms on chembl_get_bioactivities, to reach the whole family.",
+  "type": "string"
+}

changedOutput schema / properties / molecules / items / required

Previous value: -[
-  "molecule_chembl_id",
-  "pref_name",
-  "canonical_smiles",
-  "standard_inchi_key",
-  "full_molformula",
-  "mw_freebase",
-  "alogp",
-  "num_ro5_violations",
-  "qed_weighted",
-  "max_phase",
-  "molecule_type"
-]New value: +[
+  "molecule_chembl_id",
+  "pref_name",
+  "canonical_smiles",
+  "standard_inchi_key",
+  "full_molformula",
+  "mw_freebase",
+  "alogp",
+  "num_ro5_violations",
+  "qed_weighted",
+  "max_phase",
+  "molecule_type",
+  "parent_chembl_id"
+]

changedOutput schema / properties / notice / description

Previous value: -"Guidance when nothing matched — echoes the query and suggests how to broaden."New value: +"Guidance when nothing matched — echoes the query and suggests how to broaden — the disclosure that a limit above the maximum was served at the maximum, and, when totalCountCapped is true, that the total is ChEMBL's search ceiling and how to narrow below it."

changedOutput schema / properties / totalCount / description

Previous value: -"Total compounds matching before the limit was applied."New value: +"Total compounds matching before the limit was applied — a lower bound when totalCountCapped is true."

addedOutput schema / properties / totalCountCapped

Added value: +{
+  "description": "True when totalCount is ChEMBL's ceiling for the search — 10000 for a name search, 30000 for a substructure search: at least that many compounds match, and no page past the ceiling can be reached. Narrow the query to bring the matches under it.",
+  "type": "boolean"
+}

Changed2 schema fields changedSep 26, 2026

changedOutput schema / properties / error / properties / data / properties / reason / description

Previous value: -"Machine-readable failure mode. Declared by this tool: `missing_input`: Neither query nor structure was supplied, or a structure search_type was chosen without a structure. Other values are possible when a failure originates below the handler."New value: +"Machine-readable failure mode. Declared by this tool: `not_found`: ChEMBL has no record for the requested identifier or structure. `rate_limited`: ChEMBL rate-limits the upstream request. `missing_input`: Neither query nor structure was supplied, or a structure search_type was chosen without a structure. Other values are possible when a failure originates below the handler."

changedOutput schema / properties / error / properties / data / properties / reason / examples

Previous value: -[
-  "missing_input"
-]New value: +[
+  "not_found",
+  "rate_limited",
+  "missing_input"
+]

Changed22 schema fields changedSep 19, 2026
- removedOutput schema / properties / molecules / items / properties / alogp / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / alogp / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / canonical_smiles / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / canonical_smiles / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / full_molformula / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / full_molformula / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / max_phase / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / max_phase / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / molecule_type / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / molecule_type / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / mw_freebase / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / mw_freebase / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / num_ro5_violations / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / num_ro5_violations / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / pref_name / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / pref_name / type
```
Added value: +[
+  "string",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / qed_weighted / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / qed_weighted / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / similarity / anyOf
```
Removed value: -[
-  {
-    "type": "number"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / similarity / type
```
Added value: +[
+  "number",
+  "null"
+]
```
- removedOutput schema / properties / molecules / items / properties / standard_inchi_key / anyOf
```
Removed value: -[
-  {
-    "type": "string"
-  },
-  {
-    "type": "null"
-  }
-]
```
- addedOutput schema / properties / molecules / items / properties / standard_inchi_key / type
```
Added value: +[
+  "string",
+  "null"
+]
```

Changed6 schema fields changedAug 25, 2026

changedInput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedInput schema / additionalProperties
```
Added value: +false
```

changedOutput schema / $schema

Previous value: -"http://json-schema.org/draft-07/schema#"New value: +"https://json-schema.org/draft/2020-12/schema"

addedOutput schema / anyOf

Added value: +[
+  {
+    "not": {
+      "required": [
+        "error"
+      ]
+    },
+    "required": [
+      "molecules",
+      "totalCount",
+      "truncated",
+      "shown",
+      "cap"
+    ]
+  },
+  {
+    "required": [
+      "error"
+    ]
+  }
+]

addedOutput schema / properties / error

Added value: +{
+  "additionalProperties": {},
+  "description": "Present when the call failed. Absent on success.",
+  "properties": {
+    "code": {
+      "description": "JSON-RPC error code for this failure.",
+      "maximum": 9007199254740991,
+      "minimum": -9007199254740991,
+      "type": "integer"
+    },
+    "data": {
+      "additionalProperties": {},
+      "properties": {
+        "reason": {
+          "description": "Machine-readable failure mode. Declared by this tool: `missing_input`: Neither query nor structure was supplied, or a structure search_type was chosen without a structure. Other values are possible when a failure originates below the handler.",
+          "examples": [
+            "missing_input"
+          ],
+          "type": "string"
+        },
+        "recovery": {
+          "additionalProperties": {},
+          "description": "Actionable next step for the caller.",
+          "properties": {
+            "hint": {
+              "type": "string"
+            }
+          },
+          "required": [
+            "hint"
+          ],
+          "type": "object"
+        },
+        "retryable": {
+          "description": "Whether retrying may succeed.",
+          "type": "boolean"
+        }
+      },
+      "type": "object"
+    },
+    "message": {
+      "description": "Human-readable description of what went wrong.",
+      "type": "string"
+    }
+  },
+  "required": [
+    "code",
+    "message"
+  ],
+  "type": "object"
+}

removedOutput schema / required

Removed value: -[
-  "molecules",
-  "totalCount",
-  "truncated",
-  "shown",
-  "cap"
-]

Changed3 schema fields changedAug 13, 2026

addedInput schema / properties / cursor

Added value: +{
+  "description": "Opaque continuation token from a previous call's nextCursor — resumes where that page ended. Omit for the first page. Re-send the same query/structure/filters that minted it (only limit may change; it sets this page's size); redeeming it against different filters walks a different result set.",
+  "type": "string"
+}

changedOutput schema / properties / molecules / items / properties / similarity / description

Previous value: -"Tanimoto similarity percent (0–100) to the query structure. Present only on similarity/substructure search."New value: +"Tanimoto similarity percent (0–100) to the query structure. Present only on search_type=similarity results; on every other search_type the key is absent, not null."

addedOutput schema / properties / nextCursor

Added value: +{
+  "description": "Opaque token for the next page — pass it back as cursor with the same filters. Absent when this page is the last one.",
+  "type": "string"
+}

First observedAug 13, 2026

TDQS

A4.8/5.0

Behavior5/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Annotations cover read-only/idempotent/open-world, and the description adds substantive behavior: a capped limit is silently served at 100 with a notice, nextCursor/cursor must be replayed with identical filters, and only similarity mode adds a Tanimoto percentage to the row shape. The salt/family-measurement caveat is genuinely non-obvious operational context.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Dense but front-loaded and free of filler — mode selection, constraints, return shape, chaining, and pagination each get one efficient sentence. It is slightly over-packed into a single block, which costs a point on scannability.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

For a 7-parameter search tool with an output schema, the description still names the per-row fields and the one mode-specific addition (Tanimoto), plus the pagination contract and the chaining path. An agent has everything needed to call it correctly on the first try.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is already 100%, so baseline is 3; the description earns extra credit by explaining the cross-parameter dependencies (search_type drives which of query/structure is required, cursor must be re-sent with the same filters) rather than restating field meanings. It doesn't add detail on similarity_threshold or max_phase_min beyond the schema, which keeps it off a 5.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Opens with a specific role statement ('Discovery entry point for compounds') and enumerates the four search modes with the exact input each needs (query for name, structure for exact/similarity/substructure). This clearly distinguishes it from siblings like chembl_search_targets and chembl_get_bioactivities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines5/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Explicitly states the selection condition between name and structure modes, the 'at least one of query or structure' constraint, and pauses to warn about the salt-vs-parent ranking pitfall before chaining. It also names the correct next-step tools (chembl_get_bioactivities, chembl_get_drug_info), leaving nothing to inference.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

All chembl-mcp-server tools Inspect

Try in Browser

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Glama MCP Gateway

Add one secure layer between your agents and this server.