rdkit-agent

rdkit-agent

Agent-first cheminformatics CLI powered by RDKit WASM. Validates, converts, and analyzes chemical notation (SMILES, SMIRKS, InChI) with structured JSON output. Works as a CLI, Node.js library, and MCP server.

Installation

npm install -g rdkit-agent

Requires Node.js ≥ 16. No native build steps — RDKit runs as WebAssembly.

Quick Start

# Validate a SMILES string
rdkit-agent check --smiles "c1ccccc1"

# Compute molecular descriptors
rdkit-agent descriptors --smiles "CCO"

# Convert SMILES to InChI
rdkit-agent convert --from smiles --to inchi --input "CCO"

# Find similar molecules
rdkit-agent similarity --query "c1ccccc1" --targets "Cc1ccccc1,CCO,c1ccc2ccccc2c1" --threshold 0.5

Output is JSON when stdout is not a terminal (piped/redirected). Pass --output json to force it.

Commands

Command	Description
check	Pre-flight validation for SMILES, SMIRKS, and reaction balance
repair-smiles	Deterministically repair/reconstruct malformed SMILES into valid canonical guesses
convert	Convert between SMILES, InChI, InChIKey, MOL, SDF
descriptors	Compute MW, logP, TPSA, HBD, HBA, rotatable bonds, rings
balance	Check atom balance for reactions
fg	Detect functional groups (tiered consuming SMARTS catalog)
subsearch	SMARTS substructure search
fingerprint	Generate Morgan or topological fingerprints
similarity	Tanimoto similarity search
scaffold	Extract Murcko scaffold
filter	Filter molecules by descriptor ranges (Lipinski Ro5, etc.)
draw	Render molecule to SVG/PNG with optional atom/bond highlighting
stats	Dataset statistics across descriptors
edit	Molecular transformations (neutralize, sanitize, add-h, etc.)
rings	Ring analysis (count, aromaticity, spiro atoms)
react	Apply a reaction SMIRKS to reactant SMILES → product SMILES
stereo	Stereocentre analysis (tetrahedral + E/Z, CIP codes, specified vs unspecified)
atom-map	Atom mapping: add / remove / check / list sub-commands
schema	Inspect JSON schemas for any command
mcp	Start MCP stdio server
version	Show version info

Common flags

--json '{"smiles":"CCO"}'   # Pass arguments as JSON object
--json -                    # Read JSON from stdin
--fields "MW,logP"          # Limit output to specific fields
--output json               # Force JSON output

check

rdkit-agent check --smiles "CCO"
rdkit-agent check --smiles "H2O"          # → corrects alias to "O"
rdkit-agent check --smirks "[C:1][OH]>>[C:1]=O"
rdkit-agent check --reactants "CC,OO" --products "CCO,O"

Output keys: overall_pass, summary, checks, failed_checks, fix_suggestions, corrected_values

repair-smiles

rdkit-agent repair-smiles --input "C1CC"                   # ring-closure repair
rdkit-agent repair-smiles --input "H2O"                    # alias/formula repair
rdkit-agent repair-smiles --json '{"molecules":["C1CC","Na+"]}'

Output keys: success, canonical_smiles, strategy, confidence, intent, attempts

descriptors

rdkit-agent descriptors --smiles "CCO"
rdkit-agent descriptors --json '{"molecules":["CCO","c1ccccc1"]}'
rdkit-agent descriptors --smiles "CCO" --fields "MW,logP,TPSA"

convert

rdkit-agent convert --from smiles --to inchi --input "CCO"
rdkit-agent convert --from smiles --to inchikey --input "c1ccccc1"
rdkit-agent convert --from smiles --to mol --input "CCO"

similarity

rdkit-agent similarity --query "c1ccccc1" --targets "Cc1ccccc1,CCO" --threshold 0.5 --top 5

filter

rdkit-agent filter --smiles "CCO,CC(=O)Oc1ccccc1C(O)=O" --mw-max 100 --logp-max 3
rdkit-agent filter --smiles "CCO,CC(=O)Oc1ccccc1C(O)=O" --lipinski

draw

rdkit-agent draw --smiles "c1ccccc1" --output benzene.svg --format svg
rdkit-agent draw --smiles "c1ccccc1" --width 400 --height 400 --output large.svg

# Highlight atoms 0 and 1 in red, atom 3 in blue
rdkit-agent draw --smiles "c1ccccc1" \
  --highlight-atoms '{"0":"#ff0000","1":"#ff0000","3":"#0000ff"}' \
  --highlight-radius 0.4

# Highlight bond 1 in green
rdkit-agent draw --smiles "c1ccccc1" \
  --highlight-bonds '{"1":"#00ff00"}'

--highlight-atoms and --highlight-bonds accept JSON objects mapping index (string) → CSS hex colour. --highlight-radius sets the highlight circle size (default 0.3).

edit

rdkit-agent edit --smiles "[NH4+].[OH-]" --operation neutralize
rdkit-agent edit --smiles "CCO" --operation add-h
rdkit-agent edit --smiles "[H]OCC" --operation remove-h
rdkit-agent edit --smiles "[CH3:1][OH:2]" --operation strip-maps

react

Apply a reaction SMIRKS to one or more reactant SMILES and receive the product SMILES.