Agent Setup Recipes

Agent setup recipes

This page provides copy-paste local setup for ChemDraft’s CLI, MCP server, and assistant skill on macOS and Windows.

Run setup on the computer that will execute ChemDraft. The CLI does not need the desktop application to be running. Install Git, Node 24, and pnpm 10.12.1. For name conversion, also install a JDK with jlink; set JAVA_HOME if the runtime builder cannot locate it. Build the OPSIN runtime separately on each host—do not reuse a macOS runtime on Windows.

Checkout and verify

macOS:

git clone https://github.com/jgassens/ChemDraft.git "<checkout>"
cd "<checkout>"
pnpm install
node scripts/build-opsin-runtime.mjs
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft --help
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft name --name 'ethanol'

Windows PowerShell (choose a checkout outside a synced folder):

git clone https://github.com/jgassens/ChemDraft.git "<checkout>"
Set-Location "<checkout>"
pnpm install
node scripts/build-opsin-runtime.mjs
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft --help
pnpm -s --config.shell-emulator=true --dir "<checkout>" chemdraft name --name 'ethanol'

The final name command should return JSON with ok: true and OPSIN’s SMILES. The runtime is created at apps/desktop/src-tauri/resources/opsin/jre for the current host. -s keeps stdout machine-readable; --config.shell-emulator=true prevents Windows path/backslash rewriting.

Claude Code and Codex MCP

After the checkout works, register MCP locally:

claude mcp add --scope user chemdraft -- pnpm -s --dir "<checkout>" chemdraft-mcp
codex mcp add chemdraft -- pnpm -s --dir "<checkout>" chemdraft-mcp

Then install the skill using the commands in Agent Skill. Useful prompts include:

• “Use ChemDraft to render C/C=C/C as an SVG and check its stereochemistry before returning it.”
• “Use ChemDraft to make a letter-labelled two-column grid from these confirmed SMILES.”
• “Use ChemDraft to produce an editable document first, style it, render it, and report the final canonical SMILES and warnings.”

Claude Desktop

Add this server to claude_desktop_config.json, retain other entries, and restart Claude Desktop:

{"mcpServers":{"chemdraft":{"command":"pnpm","args":["-s","--dir","<checkout>","chemdraft-mcp"]}}}

The usual configuration locations are ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. If the graphical client lacks your terminal PATH, use the full pnpm executable path. If it cannot launch pnpm.cmd, configure cmd.exe with /d /c pnpm -s --dir <checkout> chemdraft-mcp as its arguments.

Optional NMR predictor

Clone the separate predictor, follow its own dependency instructions, and set its directory only after the owner has added it to the trust file:

git clone https://github.com/jgassens/ChemDraft-NMR-Plugin.git "<plugin-checkout>"

macOS uses export CHEMDRAFT_NMR_PLUGIN_DIR="<plugin-checkout>"; Windows PowerShell uses $env:CHEMDRAFT_NMR_PLUGIN_DIR = '<plugin-checkout>'. The environment variable is not approval. The owner must manually add the absolute directory to trusted-plugins.json; see MCP Server. An assistant must not create or change that trust file.

How agent edits are controlled

The headless tools write new files and do not alter the user’s open canvas. Inside the desktop app, an agent or plugin may mutate a document only through a patch while one of its own registered commands is running. A patch is a reviewable list of allowed insertions; the host commits one labelled undo entry, selects what changed, and does not open a review window for deterministic conversion of user-provided input. Changing or removing existing content goes through proposal review instead. This keeps automation visible, undoable, and chemically accountable.

Next

• Agent Tools Overview
• Command-Line CLI
• MCP Server
• Plugin Permissions