MCP Server

MCP server

This page covers ChemDraft’s local stdio MCP server, which gives a compatible assistant structured chemistry tools.

The server calls CLI command modules in process, so it shares their validation and chemical-identity checks. Each call gets a fresh output directory. Unrequested temporary call directories are retained for up to 24 hours; returned command JSON, reports, and individual returned files are each capped at 5 MB. Reduce image width or structure size if a response exceeds that limit.

Tools

The current server registers ten tools:

Tool	Required input	Optional input	Returns
render_structure	smiles	width, background, bondLength, padding, format, outDir	JSON result plus PNG/SVG
build_document	smiles	bondLength, outDir	Editable native JSON with ids and ring keys
render_document	exactly one of documentPath, documentJson	format, width, background, padding, outDir	JSON plus SVG/PNG, PDF resource, or native document
render_grid	items (name, smiles)	labels, columns, width, gutter, padding, background, format, outDir	Grid image/SVG
render_reaction	reactionSmiles, or reactants/products arrays	agents, conditions, arrow, width, background, format, outDir	Reaction image/SVG
analyze_structure	smiles	methods, format (json or md)	Status-bearing analysis JSON and optional Markdown report
name_to_structure	name	render, allowAmbiguous	OPSIN result and optional PNG
check_stereo	smiles	—	Tetrahedral and double-bond stereo report
predict_nmr	smiles	nuclei, spectrum, statistic, ignoreLabileHydrogens	Prediction JSON and optional PNG spectrum
export_structure	smiles, format	outDir	CDXML, PDF, SDF, MOL, or SMILES result

For render_reaction, provide either a reaction SMILES or the component arrays, not both. Component arrays preserve each array entry as one molecule object, including a dot-joined salt. render_document requires exactly one document source and limits inline JSON to 5 MB. export_structure handles one molecule; use the CLI export --batch for multi-record SDF or SMILES output.

Tool success does not erase warnings. In particular, review canonical SMILES, stereo counts, renderer/export warnings, and analysis statuses. Radicals and isotope labels are refused rather than silently changed. NMR shifts are predictions, with multiplicities and J values labelled estimates.

Register the server

Run it on the computer where the assistant client runs. Replace <checkout> with an absolute path.

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

The Claude Code user scope makes the tool available in every folder. The MCP launch does not need --config.shell-emulator=true, because tool inputs arrive as JSON rather than shell arguments. Do keep -s: MCP stdio must contain protocol messages only.

For Codex, the equivalent configuration is:

[mcp_servers.chemdraft]
command = "pnpm"
args = ["-s", "--dir", "<checkout>", "chemdraft-mcp"]

On Windows TOML, use forward slashes or a literal single-quoted path. For Claude Desktop, edit claude_desktop_config.json, preserving existing servers, then restart the client:

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

Typical Claude Desktop locations are ~/Library/Application Support/Claude/ on macOS and %APPDATA%\Claude\ on Windows. If a GUI client cannot find pnpm, give command the full executable path. If Windows cannot launch a pnpm.cmd shim, use cmd.exe with arguments /d, /c, pnpm, -s, --dir, <checkout>, and chemdraft-mcp.

External plugin trust

NMR uses a separately checked-out plugin. Its directory must be listed by the owner in the version-1 trust file; the CLI and MCP server never create or edit that file. The OS account lookup selects the path: ~/.config/chemdraft/trusted-plugins.json on macOS, and normally %USERPROFILE%\.config\chemdraft\trusted-plugins.json on Windows. It does not accept HOME, USERPROFILE, or XDG_CONFIG_HOME overrides.

{"version":1,"trustedPlugins":[{"id":"org.chemdraft.nmr.predictor","dir":"<plugin-checkout>"}]}

Use an absolute path; escape Windows backslashes in JSON or use forward slashes. CHEMDRAFT_NMR_PLUGIN_DIR selects a directory but never makes an unlisted directory trusted. The allow-list is checked before plugin entry code loads, and real-path checks prevent the manifest or entry from escaping its trusted directory.

Next

• Agent Setup Recipes
• Agent Skill
• Command-Line CLI