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, and max clinical phase 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 capped result carries nextCursor — pass it back as cursor with the same filters to read the next page.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`limit`	No	Maximum molecules to return. 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

TableJSON 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.
`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.

Schema Changelog

Changes observed during successful MCP inspections.

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.5/5.0

Behavior5/5

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

Beyond the readOnly/openWorld/idempotent annotations, the description discloses mode-dependent validation ('At least one of query or structure is required, and structure is required for the three structure modes'), output variance ('only search_type=similarity adds a Tanimoto similarity percent'), and pagination ('A capped result carries nextCursor — pass it back as cursor with the same filters'). These are operational behaviors the annotations cannot express, and nothing here contradicts them.

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

Conciseness5/5

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

The purpose sentence is front-loaded and every subsequent clause earns its place: modes, input requirements, return fields, chaining, and pagination each get one clause with zero filler. Covering 7 parameters, 4 modes, and 2 downstream tools in under six sentences is remarkably economical.

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, 4-mode tool with an output schema and rich annotations, the description delivers everything needed to call it correctly: its role, mode-dependent inputs, per-mode return fields, downstream chains, and cursor semantics. The intentional omissions (limit, similarity_threshold details) are fully covered by the 100% schema documentation, and the output schema relieves the description of explaining return values.

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

Parameters3/5

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

Schema coverage is 100% — every parameter carries detailed documentation of defaults, ranges, and mode-coupling rules. The description's sentence on mode/parameter coupling is a useful consolidation but restates what the query, structure, and search_type schema entries already say. With the schema doing the heavy lifting, the rubric's baseline of 3 applies.

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?

The opening phrase 'Discovery entry point for compounds' stakes out a distinctive role among the siblings — a search/discovery tool rather than a record lookup. It enumerates the two search families (name lookups and the three structure modes) and names the accepted identifier types. The chaining guidance to chembl_get_bioactivities and chembl_get_drug_info makes it distinguishable from those get-lookup siblings without opening the schema.

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

Usage Guidelines4/5

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

The description establishes clear usage context: it is the compound discovery entry point, and results should be chained via molecule_chembl_id into chembl_get_bioactivities or chembl_get_drug_info, which effectively names the downstream alternatives. It stops short of explicit when-not guidance, such as telling an agent to go straight to chembl_get_bioactivities when it already holds a ChEMBL ID, and it does not contrast itself with chembl_search_targets.

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.