cdxml-toolkit

Platform support: Portable CDXML and RDKit workflows run on Windows, macOS, and Linux. ChemDraw COM rendering, ChemScript, and editable ChemDraw objects in Word or PowerPoint require a Windows host with a licensed desktop ChemDraw installation.

A real editable scheme

The repository produces native chemistry artifacts, not screenshot-only output. The reaction below was exported directly from the editable CDXML through ChemDraw COM; its YAML description and PNG render are retained beside the source:

YAML source · Editable CDXML · Native PNG · More scheme examples

Related MCP server: CovAiLent

What it provides

Quick start

Required: 64-bit Python 3.10–3.13. Portable CDXML and RDKit operations run without ChemDraw. Native rendering, ChemScript, and editable Office objects require Windows plus a licensed desktop ChemDraw installation. Python 3.14 is not supported yet.

conda create -n cdxml python=3.12 pip -y
conda activate cdxml

git clone https://github.com/ZiChenWang114514/cdxml-toolkit-community.git
Set-Location .\cdxml-toolkit-community

# Both distributions expose the cdxml_toolkit import package.
pip uninstall -y cdxml-toolkit
pip install -e ".[all]"

# Read-only environment and capability report.
cdxml-doctor --no-tests

The default installation includes the portable CDXML, RDKit, and MCP runtime. Optional groups are windows, office, chemscript, analysis, image, decimer, opsin, http, all, and dev.

Install the current community source directly when a checkout is unnecessary:

pip install "cdxml-toolkit-community[all] @ git+https://github.com/ZiChenWang114514/cdxml-toolkit-community.git@main"

cdxml-doctor --no-tests does not change the machine. To detect ChemDraw and prepare a compatible ChemScript environment interactively, run:

cdxml-doctor --no-tests --configure-chemscript
cdxml-doctor --json

ChemScript is optional. OPSIN provides offline IUPAC name resolution when Java is available. The wheel does not bundle a JRE; the runtime first checks JAVA_HOME and java on PATH. A pre-approved local archive can be installed with explicit integrity metadata:

$env:CDXML_TOOLKIT_JRE_ZIP = "C:\installers\temurin-jre.zip"
$env:CDXML_TOOLKIT_JRE_SHA256 = "approved sha256"
cdxml-doctor --no-tests

Archive size, extracted size, paths, links, and optional SHA-256 are checked before installation.

Connect an agent

The codex profile exposes all 35 tools. Start a local stdio server directly:

cdxml-mcp --profile codex

For Codex, add the server to %USERPROFILE%\.codex\config.toml and replace the Python path with the interpreter from the cdxml environment:

[mcp_servers.chemdraw]
command = "C:\\Users\\YOU\\miniconda3\\envs\\cdxml\\python.exe"
args = ["-m", "cdxml_toolkit.mcp_runtime", "--profile", "codex"]
startup_timeout_sec = 120
tool_timeout_sec = 600

Restart the agent, then try:

Resolve aspirin, draw it as CDXML, and render a PNG preview.

Add the server under mcpServers in %APPDATA%\Claude\claude_desktop_config.json:

{
  "mcpServers": {
    "cdxml-toolkit": {
      "command": "C:\\Users\\YOU\\miniconda3\\envs\\cdxml\\python.exe",
      "args": ["-m", "cdxml_toolkit.mcp_runtime", "--profile", "codex"]
    }
  }
}

The same process-based configuration works with other MCP-compatible agents.

Copy CLAUDE.md into an agent workspace when the client supports project instructions. It tells the agent to obtain molecular structures from tools, use OCSR for images, preserve chemical semantics, and verify transformations instead of inventing structure strings.

How the runtime works

Important runtime properties:

• Tool calls run in subprocess workers with configurable hard timeouts and structured errors.

• ChemDraw, Word, and PowerPoint automation share serialized native-resource coordination.

• Output-producing tools validate artifacts and avoid unintentionally replacing existing files.

• Metrics record counts, duration, timeouts, worker failures, and queue length without tool arguments or molecular content.

• get_toolkit_capabilities reports the available local features before an agent chooses a workflow.

Tool profiles

Choose the smallest useful profile to reduce tool-selection noise:

The generated MCP tool reference and JSON schema contain the exact live signatures. CI checks both files for drift.

Streamable HTTP

Stdio remains the local default. An activated Windows workstation can serve a trusted remote computer after installing the http extra:

$env:CHEMDRAW_MCP_HTTP_API_KEY = "generate-a-long-random-value"
cdxml-mcp --transport streamable-http --host 0.0.0.0 --port 8029 `
  --allowed-host chemdraw-host.example:8029 `
  --allowed-origin https://trusted-client.example

Remote binding requires a bearer key and an explicit host list. /health contains no molecule data; /metrics requires authentication when the server is remotely reachable.

DECIMER image upload is disabled by default. Remote recognition requires confirm_upload=true, validates that the payload decodes as an image, and enforces request and response limits.

Command line

The scheme renderer accepts YAML, reaction JSON, and a compact text syntax described in the showcase catalog.

Development

python -m pip install -e ".[dev,windows,office,analysis,image]"
python -m pytest -m "not network" -q
python -m build
python -m twine check dist/*

Hosted CI checks Python 3.10–3.13, MCP SDK 1.x and 2.x, generated references, portable tests, and distributions. Native ChemDraw, ChemScript, Word, and PowerPoint checks run on a licensed Windows workstation.

Read the contribution guide, security policy, and maintenance guide before proposing or releasing changes.

Community stewardship

This repository continues leehiufung911/cdxml-toolkit. The distribution is cdxml-toolkit-community; the compatible Python import remains cdxml_toolkit.

• Community maintainer: ZiChenWang114514

• Original author: Hiu Fung Kevin Lee (@leehiufung911)

• Third-party data and component notices: NOTICE.md

• License: MIT

The original project was directed by Hiu Fung Kevin Lee, a PhD organic chemist, and documented as built and tested with Claude Code (Opus 4.6).