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.

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

Behavior5/5

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

Annotations carry the read-only/idempotent/open-world profile, and the description adds substantial behavior on top: the pagination contract ('A capped result carries nextCursor — pass it back as cursor with the same filters'), the mode-conditional output composition ('only search_type=similarity adds a Tanimoto similarity percent'), and per-mode input requirements. Nothing contradicts the annotations.

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?

Roughly 100 words cover purpose, four modes, input requirements, return composition, chaining, and pagination in a logical flow. Every sentence carries operational content, and the core mode contract is front-loaded ahead of output and pagination details. Nothing is redundant with the schema.

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?

Given the tool's complexity — 7 parameters, 4 modes, pagination, and an output schema — the description covers every decision an agent must make before calling: which mode to use, which input to supply, and how to page through results. Return-value details are already handled by the output schema, and parameter ranges by the schema; nothing needed for correct invocation is missing.

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 100%, so the schema already documents every parameter; the description's key addition is the cross-parameter invariant 'At least one of query or structure is required' — a rule the schema cannot express with zero required fields. It also clarifies that similarity_threshold only matters in similarity mode. The at-least-one constraint meaningfully improves invocation correctness, pushing it just above the high-coverage baseline of 3.

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 description names a specific verb ('Find') against a concrete resource ('compounds' in ChEMBL) and enumerates the four search modes with their required inputs. It positions itself as the 'Discovery entry point' for molecules, which distinguishes it from sibling tools like chembl_search_targets, chembl_get_bioactivities, and chembl_get_drug_info. The scope is unambiguous and mode-specific.

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 when to use the tool ('Discovery entry point') and routes downstream work by instructing 'Chain molecule_chembl_id into chembl_get_bioactivities or chembl_get_drug_info.' It also states the input contract per mode (query vs structure). It does not explicitly state when-not-to-use or provide selection conditions among siblings such as chembl_search_targets, so it stops short of full exclusion criteria.

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.