ochem-mcp

An MCP (Model Context Protocol) server that enables Claude Desktop to generate organic chemistry diagrams, including molecules, reactions, and reaction mechanisms with electron-pushing arrows.

Features

• Draw Molecules: Render any molecule from SMILES notation
• Look Up Molecules: Convert common names (aspirin, caffeine, etc.) to SMILES
• Draw Reactions: Show complete reaction schemes with arrows and conditions
• Draw Mechanisms: Electron-pushing arrows for reaction mechanisms

Requirements

• Node.js 18+ is required (for the sharp image processing library)

Installation

Quick Install (npx)

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "ochem": {
      "command": "npx",
      "args": ["-y", "ochem-mcp"]
    }
  }
}

Then restart Claude Desktop.

For nvm users

If you use nvm, Claude Desktop may pick up an old Node version. Specify the full path to Node 18+:

{
  "mcpServers": {
    "ochem": {
      "command": "/Users/YOU/.nvm/versions/node/v20.x.x/bin/node",
      "args": ["/Users/YOU/.nvm/versions/node/v20.x.x/bin/npx", "-y", "ochem-mcp"]
    }
  }
}

Replace the paths with your actual Node 18+ installation path (run which node after nvm use 20).

Local Development

# Clone and install
cd ochem-mcp
npm install
npm run build

# Add to Claude Desktop config
{
  "mcpServers": {
    "ochem": {
      "command": "node",
      "args": ["/path/to/ochem-mcp/dist/index.js"]
    }
  }
}

Usage Examples

Draw a Molecule

Ask Claude:

"Draw the structure of caffeine"

Claude will use lookup_molecule to find the SMILES, then draw_molecule to render it.

Draw a Reaction

"Show me the esterification reaction between acetic acid and ethanol"

Claude will render:

CH3COOH + C2H5OH → CH3COOC2H5 + H2O
        H2SO4, heat

Draw a Mechanism

"Show the SN2 mechanism for bromide attacking chloromethane"

Claude will draw the molecule with curved arrows showing electron movement.

Available Tools

draw_molecule

Draw a molecule from SMILES notation.

| Parameter | Type | Description | |-----------|------|-------------| | smiles | string | SMILES notation (required) | | width | number | Image width in pixels (default: 400) | | height | number | Image height in pixels (default: 300) | | showAtomIndices | boolean | Show atom numbers | | showHydrogens | boolean | Show explicit H atoms (useful for carbocations) | | highlightAtoms | number[] | Atom indices to highlight | | highlightColor | string | Hex color for highlights |

lookup_molecule

Convert common name to SMILES.

| Parameter | Type | Description | |-----------|------|-------------| | name | string | Common molecule name (required) |

Database includes 100+ molecules: drugs, amino acids, nucleobases, neurotransmitters, vitamins, solvents, and common organics.

draw_reaction

Draw a reaction scheme.

| Parameter | Type | Description | |-----------|------|-------------| | reactants | string[] | SMILES for reactants (required) | | products | string[] | SMILES for products (required) | | reagents | string | Conditions above arrow | | arrowType | string | "forward", "equilibrium", or "retro" | | width | number | Image width (default: 800) | | height | number | Image height (default: 300) |

draw_mechanism

Draw mechanism with electron-pushing arrows.

| Parameter | Type | Description | |-----------|------|-------------| | smiles | string | Molecule SMILES (required) | | arrows | object[] | Arrow definitions (required) | | arrows[].from | number, object | Source: atom index, { atom: N, lonePair: true }, or { bond: [A, B] } | | arrows[].to | number, object | Target: atom index or { bond: [A, B] } for bond midpoint | | arrows[].type | string | "single" (1e-, fishhook) or "double" (2e-, full arrow) | | annotations | string[] | Text labels | | width | number | Image width (default: 500) | | height | number | Image height (default: 400) |

Tip: Use draw_molecule with showAtomIndices: true first to see atom numbering for arrow placement.

SMILES Notation Quick Reference

| Structure | SMILES | |-----------|--------| | Ethanol | CCO | | Benzene | c1ccccc1 | | Acetic acid | CC(=O)O | | Acetone | CC(=O)C | | Phenol | Oc1ccccc1 | | Aniline | Nc1ccccc1 |

Lowercase = aromatic, uppercase = aliphatic. Parentheses for branching. Numbers for rings.

Carbocations

| Type | SMILES | |------|--------| | Secondary | C[CH+]C | | Tertiary | CC([C+])(C)C | | Benzyl | [CH2+]c1ccccc1 | | In ring | C1=CC=C[CH+]C1 |

RDKit limitation (carbon only): [CH+] with a substituent at ring closure fails (e.g., C[CH+]1CCCCC1 won't parse). This is specific to carbon - other atoms like [SH+] work fine. Rearrange the SMILES so the [CH+] is not at the ring closure position.

Technical Details

• Uses RDKit.js (WebAssembly) for molecule rendering - industry standard
• SVG output for crisp rendering at any size
• All outputs under 1MB for Claude Desktop compatibility
• BSD-3-Clause license (RDKit) + MIT license (this package)

Troubleshooting

Server disconnects immediately: Usually a Node version issue. Ensure Node 18+ is being used. Check the MCP server logs:

• macOS: ~/Library/Logs/Claude/mcp-server-ochem*.log

"sharp" module errors: Clear the npx cache and restart Claude Desktop:

rm -rf ~/.npm/_npx ~/.npm/_cacache

"RDKit initialization failed": First call may take 5-10 seconds to load the WASM module. Subsequent calls are fast.

"Invalid SMILES": Check your SMILES notation. Use lookup_molecule to find correct SMILES for common molecules.

Image not showing: Ensure Claude Desktop is updated to the latest version with MCP support.

License

MIT