Metadata-Version: 2.5
Name: chemdraw-mcp
Version: 0.3.0
Summary: MCP server that turns molecule names or SMILES into publication-style 2D structure drawings (PNG/SVG via RDKit) — reaction schemes, mechanisms, spectra. Unofficial, not affiliated with Revvity.
Project-URL: Repository, https://github.com/jurimaxam-dotcom/chemdraw-mcp
Project-URL: Issues, https://github.com/jurimaxam-dotcom/chemdraw-mcp/issues
Author: jurimaxam-dotcom
License-Expression: Apache-2.0
License-File: LICENSE
Keywords: chemistry,claude,mcp,rdkit,smiles,structure-drawing
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Chemistry
Requires-Python: >=3.11
Requires-Dist: genanki>=0.13.1
Requires-Dist: lxml
Requires-Dist: matplotlib>=3.10.9
Requires-Dist: mcp
Requires-Dist: pillow
Requires-Dist: py2opsin>=1.2.0
Requires-Dist: rdkit
Requires-Dist: requests
Description-Content-Type: text/markdown

# chemdraw-mcp

<!-- mcp-name: io.github.jurimaxam-dotcom/chemdraw-mcp -->

[![CI](https://github.com/jurimaxam-dotcom/chemdraw-mcp/actions/workflows/ci.yml/badge.svg)](https://github.com/jurimaxam-dotcom/chemdraw-mcp/actions/workflows/ci.yml)
[![Release](https://img.shields.io/github/v/release/jurimaxam-dotcom/chemdraw-mcp)](https://github.com/jurimaxam-dotcom/chemdraw-mcp/releases)
[![License: Apache-2.0](https://img.shields.io/badge/license-Apache--2.0-blue)](LICENSE)

**Chat → chemical structure.** An MCP server for Claude Desktop: you describe
a molecule, a reaction or a lab result in plain words, and it draws the
figure — a print-ready PNG/SVG rendered locally with RDKit, plus an
interactive preview inside the chat. *"Draw aspirin"* is already a complete
command.

Built for pharmacy and chemistry students who spend too much time clicking
hexagons. 22 tools cover the figures a report or a slide actually needs:
structures, reaction schemes, step-by-step mechanisms, substrate-scope
figures, TLC plates, titration curves, schematic spectra, substance data
sheets, Ph.Eur. assay calculations and Anki decks.

What it costs you: one install command. Apache-2.0, no API key, no sign-up
for the server, no ChemDraw licence — you need Claude Desktop and
[uv](https://docs.astral.sh/uv/), everything else is fetched once.
Rendering runs entirely on your machine; only name resolution and the
database lookups reach the internet. ChemDraw CDXML is an optional extra
format for people who want to keep editing there, never a requirement.

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/demo.gif" alt="Live demo: 'Draw Caffein' renders an interactive structure panel in Claude Desktop" width="560"></p>

## Example output

*"Draw caffeine"* — print-ready PNG, generated by `generate_molecule`:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/caffeine.png" alt="Caffeine structure, rendered by generate_molecule" width="420"></p>

*"Show the Fischer esterification of ethanol with acetic acid"* —
`generate_reaction` renders the scheme with conditions above the arrow,
live in the chat panel:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/reaction-demo.gif" alt="Reaction scheme with conditions appearing live in the chat panel" width="640"></p>

*"Show the Fischer esterification mechanism step by step"* —
`generate_mechanism` renders curved electron-flow arrows in the interactive
panel:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/mechanism-demo.gif" alt="Step-by-step Fischer esterification mechanism with curved arrows in the chat panel" width="560"></p>

*"Make a scope figure of my Suzuki couplings: 3a 92%, 3b 88% after 12 h,
3c 64% with ee 94% and dr 10:1, 3d 71%"* — `generate_scope_table` sets the
general equation with its conditions on top and the products below it, on a
shared bond length and a shared caption baseline:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/scope-suzuki.png" alt="Substrate scope figure: Suzuki coupling equation with conditions on top, below it four biphenyl products labeled 3a to 3d with yields and ee/dr notes" width="760"></p>

*"Sketch the IR spectrum of ethyl acetate"* — `generate_spectrum` (draws the
peaks it is given, with per-type axis conventions):

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/ethyl-acetate-ir.png" alt="Schematic IR spectrum of ethyl acetate with labeled bands" width="560"></p>

*"TLC of my esterification: educt at 0.30, product at 0.65, the co-spot shows
both, some educt left"* — `generate_tlc` draws the plate the lab report asks
for, with mobile phase and detection as its caption:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/tlc-esterification.png" alt="TLC plate sketch with four lanes: educt at Rf 0.30, reaction lane with a faint educt spot and the ester at 0.65, co-spot lane with both, reference lane at 0.65" width="520"></p>

*"Show caffeine in 3D"* — `generate_3d` embeds the molecule (ETKDG + force
field) and opens a drag-to-rotate ball-and-stick viewer in the chat panel:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/3d-demo.gif" alt="Rotating 3D ball-and-stick caffeine model inside the concave viewer" width="560"></p>

*"What distinguishes ibuprofen from naproxen and ketoprofen?"* —
`compare_molecules` keeps the shared scaffold (MCS) neutral and highlights
everything that differs:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/compare-profens.png" alt="Ibuprofen, naproxen and ketoprofen side by side with differences highlighted" width="680"></p>

*"Titration curve of phosphoric acid with NaOH, phenolphthalein as
indicator"* — `generate_titration_curve` computes pH from the exact charge
balance, with equivalence points, buffer points (pH = pKa) and the indicator
band; its sibling `generate_species_distribution` shows which protonation
species dominates at every pH:

<p align="center">
  <img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/titration-phosphoric.png" alt="Titration curve of phosphoric acid with three equivalence points and phenolphthalein band" width="420">
  <img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/species-phosphoric.png" alt="Species distribution of phosphoric acid over pH with pKa crossovers" width="420">
</p>

*"Create an Anki deck with important molecules and open it in Anki"* —
`export_anki_deck` / `export_curated_deck` build a ready-to-import `.apkg`
with rendered structures embedded; with the optional AnkiConnect add-on the
cards land straight in the running Anki, no clicks:

<p align="center"><img src="https://raw.githubusercontent.com/jurimaxam-dotcom/chemdraw-mcp/main/assets/anki-demo.gif" alt="Split screen: asking Claude for an Anki deck, cards appear in Anki via AnkiConnect" width="760"></p>

## Features

All 22 tools the server exposes. Files are written to `~/ChemDraw-Output/`;
every drawing tool also returns a live preview for the in-chat panel.

**Structures and schemes**

- **`generate_molecule`** — name/SMILES → 2D structure as PNG + SVG
  (optionally CDXML), with properties, functional-group detection and a
  Lipinski rule-of-five check
- **`batch_generate`** — a whole list of structures in one call
- **`generate_reaction`** — educts + products + conditions → reaction scheme
  with the conditions set above the arrow
- **`generate_mechanism`** — curved-arrow mechanisms (SN1, SN2, Fischer
  esterification) step by step
- **`generate_scope_table`** — the substrate-scope figure of the methodology
  literature: the general equation with its conditions on top, below it a
  grid of products, each with identifier ("1a") and yield ("78%") plus
  optional ee/dr/time. All structures share one bond length, all captions one
  baseline; an entry that cannot be resolved is reported, not fatal
- **`compare_molecules`** — 2–4 structures side by side, differences
  highlighted, shared scaffold (MCS) neutral
- **`generate_3d`** — rotatable 3D ball-and-stick conformer in the chat
  panel (ETKDGv3 + force field) plus SDF export

**Lab results and analysis**

- **`generate_spectrum`** — schematic spectra from peak lists (IR, NIR,
  Raman, UV/Vis, fluorescence, ORD, CD, ¹H/¹³C NMR, MS) with per-type axis
  conventions — draws given peaks, does not predict spectra
- **`generate_tlc`** — TLC plate sketch from Rf values: start line at the
  bottom, solvent front at the top, one captioned lane per application
  point (educt / reaction / co-spot), Rf annotated at every spot, mobile
  phase and detection printed as a caption — the sketch a lab report asks for
- **`generate_titration_curve`** — pH vs. titrant volume from the exact
  charge balance, with equivalence points, buffer points (pH = pKa) and
  indicator transition band
- **`generate_species_distribution`** — protonation species fractions
  over pH (Henderson–Hasselbalch) with pKa crossovers marked
- **`calculate_validation`** — Ph.Eur.-style content determination with full
  calculation steps, t-test/F-test statistics

**Substance data** (online lookups)

- **`lookup_compound`** — compound properties from PubChem
- **`lookup_safety`** — GHS hazard statements, pictograms, signal word
- **`lookup_physical`** — melting/boiling point, solubility, density
- **`lookup_biochem`** — ChEBI classification plus related UniProt entries
- **`lookup_pathway`** — metabolic pathways from KEGG
- **`lookup_molecule_data`** — PubChem + GHS combined into one data sheet
  for the in-chat panel

**Exam prep**

- **`export_anki_deck`** — flashcards as a ready-to-import Anki `.apkg`:
  structure↔name drills (optionally reversed: one note, both directions),
  cloze/fill-in-the-blank cards, identity/detection reactions, spectrum
  band assignment — with rendered images embedded, per-card tags,
  `Parent::Child` subdecks; re-exporting a deck updates cards instead of
  duplicating them. Optional delivery straight into the running Anki via
  the AnkiConnect add-on
- **`export_curated_deck`** — small, formula-verified starter decks
  (classic analgesics, Ph.Eur. identity reactions)

**Files and apps**

- **`save_png`** — persist a PNG the chat panel rendered (e.g. after the
  one-click export) to `~/ChemDraw-Output/png/`
- **`open_chemdraw_file`** — macOS only, optional: open a generated
  `.cdxml`/`.cdx` in ChemDraw for further editing

Two optional vault tools (`search_vault`, `read_vault_entry`) appear only
when `CHEMDRAW_VAULT_PATH` is set; without it the server exposes exactly the
22 tools above.

### Options on the drawing tools

- **`formats`** — `["png","svg"]` by default; `"cdxml"` on top of that for
  `generate_molecule`, `generate_reaction` and `batch_generate`. The figure
  tools (`generate_scope_table`, `generate_tlc`, `generate_spectrum`) reject
  CDXML with a clear error instead of writing something meaningless.
- **`abbreviate_groups=True`** — draws common substituents as the labels
  chemists actually write: Ph, Bn, OMe, OAc, tBu, CO₂H, Boc, Ts, TBS.
  Worth it whenever cells get small — a scope figure stays readable because
  only what differs between the substrates remains spelled out. Available on
  `generate_molecule`, `generate_reaction`, `generate_scope_table`,
  `batch_generate`.
- **`render_style`** — a named look instead of a pile of render parameters,
  on the same four tools. `"compact"` (thin bonds, capped label size, tight
  margins) for a small figure in a two-column layout, `"presentation"`
  (double bond width, minimum font size, more padding) for a lecture slide,
  `"grayscale"` for black-and-white printing, where red and blue would
  otherwise become two indistinguishable greys. Empty means the default
  look, untouched.
- **`annotate_stereo=True`** — prints CIP descriptors (R/S, E/Z) on the 2D
  drawing (`generate_molecule`, `batch_generate`).

## Installation

Three ways in; pick one. Options 1 and 2 merge into the config idempotently,
back it up first and leave every other MCP server you have configured
untouched. Afterwards restart Claude Desktop and ask: *"draw caffeine"*.

**Option 1 — clone the repo** (recommended if you want to read or change the
code; installs uv if missing, syncs dependencies, registers the server):

```bash
git clone https://github.com/jurimaxam-dotcom/chemdraw-mcp.git
cd chemdraw-mcp && ./install.sh
```

**Option 2 — from PyPI, no clone** (needs [uv](https://docs.astral.sh/uv/)):

```bash
uv tool install chemdraw-mcp
chemdraw-install
```

`chemdraw-install` writes the Claude Desktop entry for you, using the
absolute path of the installed launcher, and prints the start command it
registered.

**Option 3 — edit the config by hand.** Add this to
`claude_desktop_config.json` under `mcpServers` (macOS:
`~/Library/Application Support/Claude/claude_desktop_config.json`):

```json
"chemdraw-tool": {
  "command": "/opt/homebrew/bin/uvx",
  "args": ["chemdraw-mcp"]
}
```

> **The one pitfall that breaks every manual install:** Claude Desktop does
> not start MCP servers from a login shell — it uses the minimal GUI PATH.
> A bare `"uvx"` or `"uv"` cannot be resolved there, and the server fails to
> start without saying so. Always put the **absolute** path that
> `which uvx` prints on *your* machine into `command`. Options 1 and 2 do
> this for you.

### Optional extras

- **A Java runtime** (e.g. `brew install openjdk`) lets
  [OPSIN](https://github.com/dan2097/opsin) parse systematic IUPAC names
  offline — including ones no database indexes. Without Java the resolver
  simply continues with the PubChem/NCI online lookup.
- **The AnkiConnect add-on** lets `export_anki_deck` push cards straight
  into a running Anki. Without it you get the `.apkg` file and import it
  yourself.
- **ChemDraw** (macOS) enables `open_chemdraw_file`. Nothing else needs it.

### Something not working? Run the doctor

```bash
chemdraw-doctor                            # after "uv tool install chemdraw-mcp"
uv run chemdraw-doctor                     # in the cloned repo
uvx --from chemdraw-mcp chemdraw-doctor    # without installing anything
```

This is the first thing to try — it turns "the server does nothing" into a
named cause. It checks the six things that make the server look dead in the
chat (RDKit rendering, the Java/OPSIN runtime, the `uv` path, the Claude
Desktop entry, the name databases, the output directory) and prints, for
every problem, the exact command that fixes it. Three levels are
distinguished: `[OK]`, `[LIMITED]` (works, but restricted) and `[FAIL]`
(broken); `[NOTE]` marks checks that simply do not apply, such as not having
Claude Desktop installed. The exit code stays 0 as long as the server is
usable, so it can run in scripts. (From a PyPI install the `uv` and Claude
Desktop checks report `[NOTE]` — they relate to the repo installer.)

## Limitations

Stated up front, so nothing surprises you in a report:

- **Java is optional, and that has a price.** Without a JRE, OPSIN is
  skipped and names are resolved online via PubChem/NCI — so name lookups
  need an internet connection and only work for names those databases index.
  SMILES input never touches the network.
- **Spectra are schematic.** `generate_spectrum` draws the peaks it is
  handed, with the right axis conventions for the spectrum type. It measures
  nothing and predicts nothing — if the peak values came from the chat rather
  than from your instrument, verify them before they go into a report.
- **TLC intensity is a drawing hint.** The optional `intensity` (0…1) makes
  a spot fainter on the sketch. It is not densitometry and carries no
  quantitative meaning.
- **CDXML is a side path.** It is written from the RDKit molecule and
  round-trip validated, but PNG/SVG are the primary outputs and the ones the
  pixel tests cover. CDXML is off by default and limited to structures and
  reaction schemes — TLC plates, scope figures and spectra reject it.
- **3D is one conformer.** `generate_3d` embeds with ETKDGv3 and optimizes
  with MMFF (UFF as fallback). That is a plausible geometry for looking at,
  not a conformational search and not an energy statement.
- **The ChemDraw bridge is macOS-only** and needs a locally installed
  ChemDraw. Everything else works without it.

## How it works

```
name / SMILES
   │
   ▼
resolver ──► OPSIN (systematic IUPAC names, offline) ──► PubChem / NCI (names)  ·  direct parse (SMILES)
   │
   ▼
RDKit 2D coordinates ──► validation (sanity, round-trip)
   │
   ├──► image_export   → PNG + SVG files          (primary, offline)
   ├──► svg_renderer   → interactive chat preview (MCP App resource)
   └──► cdxml_writer   → ChemDraw CDXML           (optional, on request)
```

## Development

Python 3.11+, package manager `uv`.

```bash
uv sync                      # backend deps
cd chemdraw_tool/ui && npm install && npx playwright install chromium  # frontend, once
./test.sh                    # the gate: pytest + JS unit + headless-Chromium e2e
```

600+ tests, written test-first. The e2e test rasters a real RDKit SVG in
headless Chromium and compares it against an exact pixel snapshot — the
export path and the in-chat preview are held to the same drawing constants.

## License

Apache-2.0 — see [LICENSE](LICENSE). Copyright 2026 jurimaxam-dotcom.

> **Disclaimer:** This is an unofficial, independent project, not affiliated
> with or endorsed by Revvity. *ChemDraw* is a trademark of Revvity Signals
> Software, Inc. This tool does not include or require ChemDraw; it can
> optionally export files in the open CDXML format.
