Skip to main content
affpapa.org
RU EN
skill CX Codex

chembl-database — Claude Code skill: query the ChEMBL database

A skill that lets your agent pull molecules, targets, bioactivity, approved drugs and structure matches from ChEMBL.

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓ 
npx skills add google-deepmind/science-skills --skill chembl-database -a claude-code
npx skills add google-deepmind/science-skills --skill chembl_database -a claude-code
Open on GitHub

What chembl-database does

The skill wraps the ChEMBL HTTP API in a single script, scripts/chembl_api.py, driven by subcommands. The agent runs it with uv run, and every subcommand requires an --output flag, so each JSON result lands in a file. Read that file with jq or your own code: list results come back as an array keyed by the endpoint name, such as molecules or activities.

Coverage is broad. Fetch a molecule by ChEMBL ID, search by name, batch-fetch a list of IDs, or filter on properties like molecular weight. Targets, activities filtered by target_chembl_id and standard_type, drug details, indications, warnings and mechanisms of action each have their own subcommand. Similarity and substructure searches run server-side, so no local RDKit install is needed. A 2D structure image comes out as SVG or PNG.

Two things to set up first. uv has to be installed and on PATH. The skill also asks you to notify the user about ChEMBL's terms and drop .licenses/chembl_database_LICENSE.txt in the workspace root if it isn't there yet. Route every API call through the script — it enforces the rate limit and retries on network errors, so reaching for curl defeats the point. Bioactivity values arrive in mixed units (nM, µM, pM); pass --normalize to convert them to nM, and each record gains normalized_value_nM and normalization_note.

What it helps with

  • look up a molecule by name and get its ChEMBL ID
  • pull IC50 activities for a target with a type filter
  • convert bioactivity values to a single unit for comparison
  • check indications and mechanism of action for an approved drug
  • find similar compounds from a SMILES string without local RDKit

Example prompts for the agent

  • find aspirin in ChEMBL and show its properties
  • pull IC50 values for target CHEMBL203 and normalize them to nM
  • download the SVG structure image for CHEMBL25

How to install chembl-database

1Skills CLI (Vercel)

npx skills add google-deepmind/science-skills --skill chembl-database -a claude-code
npx skills add google-deepmind/science-skills --skill chembl_database -a claude-code

2Manually: put the files in place

~/.claude/skills/chembl_database/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/chembl_database/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about chembl-database

How do I install chembl-database in Claude?

Run npx skills add google-deepmind/science-skills --skill chembl-database -a claude-code, then npx skills add google-deepmind/science-skills --skill chembl_database -a claude-code. The skill file ends up at ~/.claude/skills/chembl_database/SKILL.md.

What does chembl-database do?

It gives your agent access to ChEMBL through scripts/chembl_api.py: molecules, targets, bioactivity, drugs, indications, mechanisms of action and structure searches. Every query writes its result to a file.

What do I need before using the skill?

uv installed and on PATH, plus a .licenses/chembl_database_LICENSE.txt file in the workspace root, which the skill creates after notifying you about ChEMBL's terms. All API calls go through the script because it enforces the rate limit and retries on network errors.

Source text

SKILL.md · Apache-2.0 
---
name: chembl-database
description: >
  Query the ChEMBL database for bioactive molecules, drug targets, bioactivity
  data, approved drugs, and chemical structures. Use when the user asks about
  compounds, targets, IC50/Ki values, drug mechanisms, or structure searches.
---

# ChEMBL Database Query

## Prerequisites

1.  **`uv`**: Read the `uv` skill and follow its Setup instructions to ensure
    `uv` is installed and on PATH.
2.  **User Notification**: If .licenses/chembl_database_LICENSE.txt does not
    already exist in the workspace root directory then (1) prominently notify
    the user to check the terms at
    https://chembl.gitbook.io/chembl-interface-documentation/about, then (2)
    create the file recording the notification text and timestamp.

## Core Rules

-   [!IMPORTANT] **Use the Utility Scripts**: You MUST ALWAYS use the provided
    utility script `scripts/chembl_api.py` for all ChEMBL API interactions,
    including checking status. NEVER use `curl` or custom Python requests to
    query the ChEMBL API directly. This ensures rate limit is enfoced and also
    retries on network errors.

-   **Output to File (Required)**: The `--output` flag is **required** for every
    subcommand. All JSON results are written to the specified file. After
    running the command, read the output file with jq or your own code to
    extract the data. List results are typically wrapped in a JSON array keyed
    by the endpoint name (e.g., `molecules`, `activities`).

-   **Notification**: If this skill is used, ensure this is mentioned in the
    output.

## Utility Script

All ChEMBL API queries use one script with subcommands:

```bash
uv run scripts/chembl_api.py <subcommand> --output <file> [options]
```

--------------------------------------------------------------------------------

### 1. Check API Status

```bash
uv run scripts/chembl_api.py status --output /tmp/status.json
```

--------------------------------------------------------------------------------

### 2. Molecule Queries

**Fetch by ChEMBL ID:** `bash uv run scripts/chembl_api.py molecule --id
CHEMBL25 --output /tmp/mol.json`

**Search by name:** `bash uv run scripts/chembl_api.py molecule --search
"aspirin" --limit 3 --output /tmp/mol_search.json`

**Batch fetch:** `bash uv run scripts/chembl_api.py molecule --ids
"CHEMBL25;CHEMBL1642" --limit 10 --output /tmp/mol_batch.json`

**Filter by properties:** `bash uv run scripts/chembl_api.py molecule --filter
molecule_properties__mw_freebase__lte=500 --limit 5 --output
/tmp/mol_filter.json`

**Filter by range:** `bash uv run scripts/chembl_api.py molecule --filter
molecule_properties__mw_freebase__range=150,200 --limit 5 --output
/tmp/mol_range.json`

**Download SDF structure file:** `bash uv run scripts/chembl_api.py molecule
--id CHEMBL25 --dl_format sdf --output /tmp/aspirin.sdf`

> **Tip**: SDF/MOL files can be passed directly to tools like PyMOL or RDKit for
> 3D visualization and analysis.

--------------------------------------------------------------------------------

### 3. Target Queries

**Search for targets:** `bash uv run scripts/chembl_api.py target --search
"EGFR" --limit 5 --output /tmp/targets.json`

**Fetch by ID:** `bash uv run scripts/chembl_api.py target --id CHEMBL203
--output /tmp/egfr.json`

--------------------------------------------------------------------------------

### 4. Bioactivity Data

**Fetch activity by ID:** `bash uv run scripts/chembl_api.py activity --id 31863
--output /tmp/act.json`

**Search activities:** `bash uv run scripts/chembl_api.py activity --search
"EGFR" --limit 5 --output /tmp/act_search.json`

**Filter activities for a target:** `bash uv run scripts/chembl_api.py activity
--filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 10 --output
/tmp/egfr_ic50.json`

**Normalize bioactivity units to nM:** `bash uv run scripts/chembl_api.py
activity --filter target_chembl_id=CHEMBL203 standard_type=IC50 --limit 5
--normalize --output /tmp/egfr_normalized.json`

> **Important**: Bioactivity values come in various units (nM, µM, pM). Use
> `--normalize` to convert all values to nM for consistent comparison. Each
> record will include `normalized_value_nM` and `normalization_note`.

--------------------------------------------------------------------------------

### 5. Drug Information

**Fetch drug details:** `bash uv run scripts/chembl_api.py drug --id CHEMBL25
--output /tmp/drug.json`

**Drug indications:** `bash uv run scripts/chembl_api.py drug_indication
--filter molecule_chembl_id=CHEMBL25 --limit 10 --output /tmp/indications.json`

**Filter indications by phase:** `bash uv run scripts/chembl_api.py
drug_indication --filter molecule_chembl_id=CHEMBL25 max_phase_for_ind=4.0
--limit 10 --output /tmp/approved_indications.json`

**Drug warnings:** `bash uv run scripts/chembl_api.py drug_warning --limit 5
--output /tmp/warnings.json`

**Mechanisms of action:** `bash uv run scripts/chembl_api.py mechanism --filter
molecule_chembl_id=CHEMBL25 --limit 5 --output /tmp/mech.json`

--------------------------------------------------------------------------------

### 6. Structure-Based Searches

> **Note**: Both similarity and substructure searches are performed
> **server-side** on ChEMBL's pre-indexed database. They do not require a local
> RDKit installation.

**Similarity search (SMILES + threshold):** `bash uv run scripts/chembl_api.py
similarity --smiles "CC(=O)Oc1ccccc1C(=O)O" --similarity 85 --limit 5 --output
/tmp/similar.json`

**Substructure search (SMILES):** `bash uv run scripts/chembl_api.py
substructure --smiles "c1ccccc1" --limit 5 --output /tmp/substruct.json`

--------------------------------------------------------------------------------

### 7. Compound Image

Download a 2D structure image (SVG by default, scalable for publication):

```bash
uv run scripts/chembl_api.py image --id CHEMBL25 --output /tmp/chembl25.svg
```

*Options:*

-   `--dimensions`: Image size in pixels (max 500, default 500).
-   `--engine`: Rendering engine (default: rdkit).
-   `--img_format`: Output format — `svg` (default, vector) or `png` (raster).

--------------------------------------------------------------------------------

### 8. Cross-Referencing with Other Databases

ChEMBL integrates with UniProt, Ensembl, PubChem, and other databases. Common
cross-referencing patterns:

**Find a ChEMBL target from a UniProt accession:** `bash uv run
scripts/chembl_api.py target --filter target_components__accession=P00533
--limit 5 --output /tmp/uniprot_target.json`

**Resolve any ChEMBL ID to its entity type:** `bash uv run scripts/chembl_api.py
chembl_id_lookup --id CHEMBL203 --output /tmp/lookup.json`

**Look up cross-reference sources:** `bash uv run scripts/chembl_api.py
xref_source --limit 10 --output /tmp/xrefs.json`

> **Tip**: Use the `target_component` endpoint to find UniProt accessions, gene
> names, and protein sequences for any ChEMBL target.

--------------------------------------------------------------------------------

### 9. Pagination

All list endpoints support `--limit` and `--offset` for pagination:

```bash
# First page: 2 results starting at offset 0
uv run scripts/chembl_api.py molecule --limit 2 --offset 0 --output /tmp/page1.json

# Second page: next 2 results starting at offset 2
uv run scripts/chembl_api.py molecule --limit 2 --offset 2 --output /tmp/page2.json
```

The response includes `page_meta` with `total_count`, `limit`, `offset`, `next`,
and `previous` links. Use successive `--offset` values to page through large
result sets.

--------------------------------------------------------------------------------

### 10. Other Endpoints

All remaining endpoints follow the same pattern:

```bash
uv run scripts/chembl_api.py <subcommand> --output <file> [--id ID | --ids ID1;ID2 | --search QUERY] [--limit N] [--offset N] [--filter KEY=VAL ...]
```

**Key subcommands at a glance:**

-   `molecule` (searchable: true): Molecules/compounds — the primary entry point
-   `target` (searchable: true): Drug targets (proteins, organisms, etc.)
-   `activity` (searchable: true): Bioactivity data (IC50, Ki, EC50, etc.)
-   `drug` (searchable: false): Approved drugs
-   `mechanism` (searchable: false): Mechanisms of action
-   `assay` (searchable: true): Assay descriptions
-   `similarity` (searchable: false): Similarity search (special)
-   `substructure` (searchable: false): Substructure search (special)
-   `image` (searchable: false): Compound image download (special)

**Full subcommand list:**

-   `activity_supp` (searchable: false): Supplementary activity data
-   `assay_class` (searchable: false): Assay classifications
-   `atc_class` (searchable: false): ATC drug classifications
-   `binding_site` (searchable: false): Binding site information
-   `biotherapeutic` (searchable: false): Biotherapeutic molecules
-   `cell_line` (searchable: false): Cell line details
-   `chembl_id_lookup` (searchable: true): ChEMBL ID resolution
-   `chembl_release` (searchable: false): Database release info
-   `compound_record` (searchable: false): Compound records
-   `compound_structural_alert` (searchable: false): Structural alerts
-   `document` (searchable: true): Literature documents
-   `document_similarity` (searchable: false): Document similarity
-   `drug_indication` (searchable: false): Drug indications
-   `drug_warning` (searchable: false): Drug safety warnings
-   `go_slim` (searchable: false): GO slim terms
-   `metabolism` (searchable: false): Metabolism data
-   `molecule_form` (searchable: false): Molecule forms (salts/parents)
-   `organism` (searchable: false): Organisms
-   `protein_classification` (searchable: true): Protein classifications
-   `source` (searchable: false): Data sources
-   `target_component` (searchable: false): Target protein components
-   `target_relation` (searchable: false): Target relationships
-   `tissue` (searchable: false): Tissue types
-   `xref_source` (searchable: false): Cross-reference sources
-   `status` (searchable: false): API status check (special)

## Common Options

-   `--output FILE`: **Required.** Output file path for JSON results.
-   `--id ID`: Fetch a single record by ID.
-   `--ids ID1;ID2;...`: Batch fetch multiple records.
-   `--search QUERY`: Free-text search (only for searchable endpoints, marked
    ✓).
-   `--limit N`: Max results to return (default: 5).
-   `--offset N`: Pagination offset.
-   `--filter KEY=VAL`: Filter parameters (can specify multiple).
-   `--normalize`: (activity only) Normalize values to nM.
-   `--dl_format sdf|mol`: (molecule only) Download structure file.

## Reference

-   **API Endpoints Reference**: See
    [references/api_endpoints.md](references/api_endpoints.md) for the full list
    of endpoints and filter operators.

## Workflow

1.  Use `status --output /tmp/status.json` to verify the API is available.
2.  Search for targets, molecules, or drugs using the relevant subcommand.
3.  Read the output JSON file to extract IDs and data.
4.  Use IDs from search results to fetch detailed records.
5.  Query `activity` with filters to get bioactivity data for targets/molecules.
    Use `--normalize` when comparing values across studies.
6.  Use `similarity` or `substructure` for server-side structure-based queries.
7.  Download compound images with `image` or structure files with `molecule
    --dl_format sdf`.
8.  Use `target --filter target_components__accession=<UniProt>` to cross-
    reference with UniProt.

© google-deepmind · Apache-2.0 · google-deepmind/science-skills

Similar skills

Everything for Science and research →
database-lookup K-Dense-AI Queries 80 documented public database APIs with explicit filters, pagination, and provenance. It is useful when scientific or financial facts require reproducible citations. CX Codex +1 2,100installs chembl-skill official OpenAI This skill queries the ChEMBL API for activity, molecule, target, mechanism, and text-search data. Use it when you need concise summaries of ChEMBL records. CX Codex GP ChatGPT 13installs tooluniverse-target-research mims-harvard Gathers target intelligence across 9 research paths: tissue expression, genetic evidence, safety, and druggability. Useful for target evaluation in drug discovery projects. CX Codex +1 409installs target-prioritization Agents365-ai The skill builds a per-gene dossier from UniProt, OpenTargets, PubMed, HPA and ChEMBL, then re-ranks your candidate genes by a composite score. CX Codex +1 2,900installs tooluniverse-gwas-drug-discovery mims-harvard Connects GWAS disease loci to causal genes, evaluates druggability, and prioritizes repurposing candidates via Open Targets and ChEMBL. CX Codex +1 386installs bioservices K-Dense-AI Guides Python workflows using BioServices to query biological databases. Useful for mapping protein IDs, extracting KEGG pathways, and resolving chemical identifiers. CX Codex +1 1,900installs

From the same set39

human-protein-atlas-database Retrieves semi-quantitative protein expression levels and subcellular localisation data from the Human Protein Atlas. Useful for validating human protein presence across tissues. CX Codex +1 2,200installs opentargets-database This skill gives your agent GraphQL access to the Open Targets Platform: target-disease associations, drug data and tractability scores. CX Codex +1 2,200installs ensembl-database Resolves gene symbols into ENSG, ENST and ENSP IDs, pulls sequences and predicts variant effects with VEP. Useful when genomic data lives in your terminal. CX Codex +1 2,200installs clinvar-database Queries ClinVar for clinical significance, review status, and pathogenicity of genomic variants. Useful for variant interpretation and benchmark controls. CX Codex +1 2,200installs alphagenome-single-variant-analysis A skill that runs one genetic variant in chr:pos:ref>alt form through the AlphaGenome API and reports expression, chromatin and histone effects. CX Codex +1 2,200installs uniprot-database Retrieves protein metadata, function annotations, and sequences from UniProtKB, UniParc, and UniRef. Useful for mapping database identifiers and streaming entries. CX Codex +1 2,200installs openfda-database Queries, counts and downloads records from the openFDA API. Use it for FDA safety events, recalls, labels, NDC lookups and regulatory data searches. CX Codex +1 2,200installs pymol A PyMOL skill that renders protein and molecular structures, runs alignments, and measures distances or contacts. Useful when you already have a structure file and need an image or a number. CX Codex +1 2,200installs

Project sponsors

Companies that keep this analytics open
Gold sponsor
Nutra.Club

Impressions, clicks and code copies — open statistics. We keep the numbers public for the same reason NeBlask itself is public. Become a sponsor