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

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.

rdkit-agent react --smirks "[C:1][OH]>>[C:1]Br" --reactants "CCO,CCCO"
# → { "reaction": "...", "reactant_count": 2, "products": [["CCBr"], ["CCCBr"]] }

Reactants can be comma-separated or space-separated (positional args after the flags).

WASM note: requires get_rxn / run_reactants in the WASM build. If those are absent a NOT_SUPPORTED_IN_WASM error is thrown — see WASM Limitations.

Programmatic:

const { reactionApply } = require('rdkit-agent');
const result = await reactionApply({ smirks: '[C:1][OH]>>[C:1]Br', reactants: ['CCO', 'CCCO'] });

stereo

Analyse stereocentres in a molecule. Reports tetrahedral and E/Z stereocentres with specified/unspecified status and CIP codes when available.

rdkit-agent stereo --smiles "CC(O)C(N)C"
# → { stereo_centers: [...], stereo_center_count: 2, specified_count: 0, has_unspecified_stereo: true }

rdkit-agent stereo --smiles "OC1=CC=CC=C1,CC(F)Cl"  # comma-separated batch

The --enumerate flag will attempt to list all stereo isomers. This requires enumerate_stereocenters in the WASM build — see WASM Limitations.

Programmatic:

const { analyzeStereo } = require('rdkit-agent');
const result = await analyzeStereo('CC(O)C(N)C');

atom-map

Manage atom mapping numbers in SMILES and SMIRKS.

# List atom_index → map_number
rdkit-agent atom-map list --smiles "[CH3:1][CH2:2][OH:3]"
# → { atom_maps: { "0": 1, "1": 2, "2": 3 }, mapped_atom_count: 3 }

# Add sequential map numbers to all heavy atoms
rdkit-agent atom-map add --smiles "CCO"
# → { mapped_smiles: "[CH3:1][CH2:2][OH:3]" }

# Strip all map numbers
rdkit-agent atom-map remove --smiles "[CH3:1][CH2:2][OH:3]"
# → { canonical_smiles: "CCO" }

# Validate SMIRKS mapping balance
rdkit-agent atom-map check --smirks "[C:1][OH:2]>>[C:1]Br"
# → { valid: true, mapped_atoms: 1, unmapped_atoms: 1, balanced: false, ... }

Programmatic:

const { atomMapList, atomMapAdd, atomMapRemove, atomMapCheck } = require('rdkit-agent');

WASM Limitations

Some RDKit features are not available in the WebAssembly build (@rdkit/rdkit). When these are called, a structured error with code: "NOT_SUPPORTED_IN_WASM" is thrown instead of silently failing.

To use these features in Python:

from rdkit import Chem
from rdkit.Chem import AllChem
from rdkit.Chem.EnumerateStereoisomers import EnumerateStereoisomers

# Reactions
rxn = AllChem.ReactionFromSmarts('[C:1][OH]>>[C:1]Br')
products = rxn.RunReactants((Chem.MolFromSmiles('CCO'),))

# Stereo enumeration
isomers = list(EnumerateStereoisomers(Chem.MolFromSmiles('CC(O)C(N)C')))

Data Files

• data/aliases.json: Alias/formula normalization map used by hardening and validation (H2O -> O, AcOH -> CC(O)=O).
• data/fg_patterns.json: Curated tiered+consuming SMARTS set used by fg for stable, low-overlap functional-group assignment.
• data/checkmol_smarts_part1.csv: Broader checkmol-derived SMARTS catalog used by repair-smiles intent scoring (ring/chain/FG hint ranking), not by the main fg command.

Claude Code Skill

Install via skills.sh for use in Claude Code and other supported agents:

npx skills add scottmreed/rdkit-agent -g

Or install the Claude Code plugin directly:

claude plugin install scottmreed/rdkit-agent

Once installed, Claude will automatically use rdkit-agent for cheminformatics tasks and can invoke it via the /rdkit-agent skill shortcut. The skill documents critical invariants, WASM speed characteristics (~1 ms warm, no Python runtime required), and all command schemas in agent-optimized format.

MCP Server (Claude Desktop)

Start the MCP stdio server to expose all commands as tools:

rdkit-agent mcp

Add to your Claude Desktop claude_desktop_config.json:

{
  "mcpServers": {
    "rdkit-agent": {
      "command": "rdkit-agent",
      "args": ["mcp"]
    }
  }
}

Node.js API

const { check, descriptors, convert, similarity, RDKIT_TOOLS, handleToolCall } = require('rdkit-agent');

// Always validate before using chemistry strings
const result = await check({ smiles: 'CCO' });
if (!result.overall_pass) {
  console.error(result.fix_suggestions);
}

// Compute descriptors
const desc = await descriptors({ smiles: 'CCO' });
console.log(desc.MW, desc.logP);

// Convert format
const inchi = await convert({ input: 'CCO', from: 'smiles', to: 'inchi' });

// Similarity search
const hits = await similarity({
  query: 'c1ccccc1',
  targets: ['Cc1ccccc1', 'CCO', 'c1ccc2ccccc2c1'],
  threshold: 0.5
});

OpenAI Tool Integration

const { RDKIT_TOOLS, handleToolCall } = require('rdkit-agent');

const response = await openai.chat.completions.create({
  model: 'gpt-4o',
  tools: RDKIT_TOOLS,
  messages: [{ role: 'user', content: 'Is CCO a valid SMILES?' }]
});

for (const toolCall of response.choices[0].message.tool_calls ?? []) {
  const result = await handleToolCall(
    toolCall.function.name,
    JSON.parse(toolCall.function.arguments)
  );
  // result is JSON-serializable
}

Exit Codes

Agent Use

Two agent-facing docs ship with the package:

• SKILL.md — verbose reference: critical invariants, error patterns, all command schemas
• skills/rdkit-agent/SKILL.md — plugin skill briefing: WASM speed context, command quick-ref, used automatically when installed via npx skills add scottmreed/rdkit-agent -g

License

MIT