Skip to main content
Glama

chemcard

Inline 2D chemical structures for AI chat explanations — an MCP App (RDKit + MCP Apps) that lets Claude or ChatGPT drop clean structure figures, reaction steps and highlights between paragraphs, like equations in a textbook.

让 AI 在讲解化学时,在文字之间插入干净、正确、紧凑的 2D 结构图:像讲义里的公式一样,而不是嵌入一个完整的化学编辑器。

chemcard 效果:讲解与结构图交替,高亮正在讲的基团

早期实验项目(v0.3)。 已在 Claude 桌面版中实测;ChatGPT 接入方式已按文档实现,但尚未实测。

能做什么

  • 画分子(draw_molecule):模型给 SMILES,服务器用 RDKit 画图。键长固定,小分子画得小,大分子不会被压缩;桥环(如托品烷)使用环系模板,画法清晰。

  • 画反应步骤(draw_reaction_step):一步一张「A + B → C」,条件写在箭头上方,可逆反应用 ⇌。讲机理时一步一张,图下紧跟这一步的讲解。

  • 高亮:用 SMARTS("C=O")或原子映射号([NH2:1])给原子和键加上彩色底色,标出正在讲的部分。

  • 点选原子:在卡片上点选原子,自动转成片段 SMILES 和带编号的 SMILES,推给模型或填入输入框;模型可以用同样的编号回过头来高亮。

  • 检查机理(check_mechanism,不显示卡片):检查每个物种的价态、意外的自由基(例如 C[N+](C)C 漏写了 H)、不稳定的碳正离子、酸碱条件矛盾,以及每一步的原子与电荷是否守恒、前后步骤是否衔接。明显的笔误会被直接拒绝,模型收到原因后自行修正。

Related MCP server: ChemGlyph

快速开始

需要 uv 和 Python ≥ 3.11。

git clone <this repo> chemcard && cd chemcard
uv sync
uv run pytest

接入 Claude 桌面版(本地运行,无需部署)

在 ~/Library/Application Support/Claude/claude_desktop_config.json 的 mcpServers 中加入下面的配置。uv 请写绝对路径(可用 which uv 查看),因为从 Dock 启动的应用读不到终端里的 PATH。

"chemcard": {
  "command": "/absolute/path/to/uv",
  "args": ["--directory", "/absolute/path/to/chemcard", "run", "chemcard"]
}

完全退出 Claude(⌘Q)再打开,新开对话问「画出阿司匹林,标出会水解的部分」。

想让模型主动画图? Claude 的连接器工具是按需加载的;问题本身没有提到「画」或「结构」时,模型往往不会去加载 chemcard。建议在 设置 → 个人资料 → 个人偏好(或项目说明)里加一句:

讲解化学时,只要涉及具体的分子、官能团或反应机理,就用 chemcard 连接器把结构画出来(draw_molecule / draw_reaction_step),并用高亮标出正在讲的部分。

接入 ChatGPT(需要公网 HTTPS,未实测)

CHEMCARD_ALLOWED_HOSTS=xxxx.ngrok-free.app uv run chemcard --http   # 监听 http://127.0.0.1:8000/mcp
ngrok http 8000

CHEMCARD_ALLOWED_HOSTS 用于放行隧道域名,否则 MCP SDK 的 DNS rebinding 防护会返回 421 Invalid Host header。然后在 ChatGPT 中选择「Add custom MCP server」,填入 https://xxxx.ngrok-free.app/mcp。

工具一览

工具

谁调用

作用

draw_molecule

模型

画一个分子,可带 highlights

draw_reaction_step

模型

画一步「A + B → C」,highlights 用 side 和 index 指明标在哪个物种上

check_mechanism

模型

画多步机理之前整体检查一遍,不显示卡片

render_structure_svg

仅卡片

宿主没有把图交给卡片时,卡片自己取图

describe_selection

仅卡片

把点选的原子转成片段 SMILES 和带编号的 SMILES

已知限制

  • 模型不一定会主动画图:需要用户侧的提示,比如个人偏好、项目说明或 Skill,见上文。

  • 化学检查只查账面错误:查得出价态、守恒和前后衔接的问题,判断不了「这种条件下会不会这样反应」,也判断不了选择性。

  • 还没有弯箭头(电子推动箭头),在计划中。

  • Claude 是否支持 ui/update-model-context 未确认:如果不支持,点选原子后需要点「提问」,模型才知道你选了什么。

  • ChatGPT 未实测。

  • 重新打开历史对话时,chemcard 服务器需要在运行:Claude 不把 _meta 交给卡片,卡片要回服务器取图。

踩坑记录

如果你也在做 MCP Apps,这些可能帮你省点时间(均为 2026-11 在 Claude 桌面版中观察到的现象):

  • Claude 会丢掉工具参数结构里的 $ref:嵌套的模型字段会变成 items: {},模型看不到这些字段,自然也不会填。解决办法是注册工具后把参数结构展开(见 server.flatten_schema),并让每个工具的嵌套深度不超过一个已确认能完整显示的工具。

  • Claude 不把工具结果里的 _meta 交给卡片:卡片拿不到 SVG,就会显示为空白。解决办法是提供一个只给卡片调用的工具(visibility: ["app"]),让卡片通过 tools/call 自己取图。

  • 卡片向宿主报告高度 0 会导致空白卡片:内容出现之前不要发送 size-changed。

  • RDKit 的自适应画布(MolDraw2DSVG(-1, -1))会忽略 fixedBondLength:先画一遍测出实际键长,再按比例缩放坐标后重画。

  • CoordGen 给单独一个 [H+] 算出的坐标是 NaN,画出来是 0×0 的空图;桥环骨架用 CoordGen 也画得很别扭。这两种情况改用 RDKit 自带的布局算法并开启 useRingTemplates。

  • RDKit 的 SVG 声明编码为 iso-8859-1:图例里的中文会变成乱码,所以图注改放在 HTML 里。

  • RDKit 会把 C[N+](C)C 当成自由基阳离子,而不会报错:如果要防住模型漏写 H,需要自己加规则检查。

  • 模型每次调用后立刻读到的返回文字,比工具描述更能左右它的行为:「先讲这一步,再画下一步」这句提醒,写在返回文字里比写在描述里有效得多。

架构

src/chemcard/
  chem/            ① 纯化学核心:不 import mcp,可单独测试
    render.py         SMILES → SVG,分子式,标准化 SMILES,原子坐标
    highlight.py      高亮解析(SMARTS / 原子映射号 → 标准原子序号)与选区描述
    reaction.py       反应步骤的原子与电荷守恒检查
    lint.py           化学规则检查
    mechanism.py      整条机理检查(规则检查 + 守恒 + 前后衔接)
  server.py        ② MCP 适配层:注册工具和资源、组装返回值,不做化学计算
  descriptions.py     模型读到的所有文字(工具描述、服务器说明、调用后的提醒)
  widgets/card.html ③ 卡片:原生 HTML/CSS/JS,只负责显示,不解析化学
tests/             pytest(100+ 个用例)
evals/             触发评测:哪些问题应该画图、图文是否穿插,以及实测记录
scripts/mock_host.py  本地模拟宿主

工具返回值分三部分,各自给不同的读者:

字段

谁能看到

放什么

content

模型和卡片(不支持 UI 的客户端只显示它)

一句文字说明,以及给模型的提醒

structuredContent

模型和卡片

精简信息:标准化 SMILES、分子式、图注、高亮

_meta

只有卡片

SVG 本体和原子坐标,不占用模型上下文

开发

uv run pytest                        # 运行测试
uv run python scripts/mock_host.py   # 本地预览:http://127.0.0.1:8765/

本地预览是一个模拟聊天页:不用接入 Claude 或 ChatGPT,就能在自己电脑上看卡片效果、切换亮/暗主题、试点选原子。

路线

版本

内容

v0.1 ✓

单分子卡片

v0.2 ✓

反应步骤卡片,以及机理检查(check_mechanism)

v0.3 ✓

高亮;点选原子回传给模型

v0.4

弯箭头:在反应物上叠加电子推动箭头,用原子映射号指定起点和终点

v0.5

电子推动校验:按箭头推算产物,并与给出的产物比对

致谢与许可

本项目使用 MIT 许可证。

本项目与 RDKit、Anthropic、OpenAI、Revvity(ChemDraw)均无关联。

Available Tools

5 tools
check_mechanismCheck mechanismA
Read-onlyIdempotent

Validate a whole multi-step mechanism before drawing it (no figure is shown). Checks every species (valid SMILES, unexpected radicals from a bracket atom missing its H, unstabilised methyl/primary cations, strong bases under acidic conditions and vice versa, doubly charged species), each step's atom and charge balance, and that every step starts from an intermediate produced by the previous step. Call it once with all steps, fix every [error], consider each [warning], then draw the steps one at a time with draw_reaction_step.

Inputs: steps (required).

describe_selectionDescribe selected atomsB
Read-onlyIdempotent

Card-internal: turn atoms the user clicked into fragment and atom-mapped SMILES.

Inputs: atoms (required), smiles (required).

draw_moleculeDraw moleculeA
Read-onlyIdempotent

Show a clean 2D structure of ONE molecule inline in the explanation. Call it when the explanation refers to a specific molecule's structure (functional groups, protecting groups, stereochemistry, why it reacts as it does). Put each figure next to the paragraph about that molecule: when comparing two molecules, draw the first, explain it, then draw the second and explain it; do not draw both first. When the text is about part of the molecule (a group, an atom, a bond), highlight that part with highlights so the reader sees what the sentence refers to. If the user selected atoms in a card, redraw from the atom-mapped SMILES they sent and highlight those atom numbers. For a reaction or mechanism step use draw_reaction_step instead. Do not call it for trivial species (H2O, HCl) or purely conceptual answers. If the tool reports invalid SMILES, fix the SMILES and call again.

Inputs: smiles (required), label, highlights.

draw_reaction_stepDraw reaction stepA
Read-onlyIdempotent

Show ONE reaction or mechanism step as a scheme 'A + B → C' (conditions over the arrow). When explaining a mechanism, go step by step: call this tool for step 1, then explain step 1 directly below it in 1–4 sentences, then call it for step 2, and so on. Never draw all steps first and explain them afterwards. A step may have 1–4 species per side. Small byproducts (H2O, H+) can go in the products or in conditions. Mark the reacting centres with highlights (e.g. the attacking atom in blue, the electrophilic carbon or the bond that breaks in red). Write charged atoms with their H explicitly ([NH+], [OH2+]); a bracket atom without H becomes a radical and the step is refused. The result reports imbalance and unusual species (methyl/primary cations, strong base in acid); if one reveals a mistake, fix the step and call again.

Inputs: products (required), reactants (required), caption, radical, +3 more.

render_structure_svgRender structure SVGB
Read-onlyIdempotent

Card-internal: fetch a drawing when the host did not deliver it in the tool result's _meta.

Inputs: smiles (required), highlight.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.9/5.0

    Scored across 5 tools

    Disambiguation4/5

    The tools mostly have distinct purposes: draw_molecule for single structures, draw_reaction_step for reaction schemes, check_mechanism for validation, and the two card-internal tools for rendering and selection parsing. The only mild overlap is between draw_molecule and render_structure_svg, but the latter is clearly marked as card-internal fallback behavior.

    Naming Consistency5/5

    All names follow a consistent snake_case verb_noun pattern: draw_molecule, draw_reaction_step, render_structure_svg, describe_selection, check_mechanism. The minor format suffix in render_structure_svg does not break the overall convention.

    Tool Count5/5

    Five tools is well-scoped for a chemistry explanation card assistant, and each tool has a clear, non-redundant role in drawing, validating, or handling user selections. No tool feels superfluous or missing from the core workflow.

    Completeness4/5

    The surface covers the main lifecycle: drawing single molecules, drawing reaction steps, validating multi-step mechanisms, and handling card-internal rendering and selections. A possible minor gap is lookup/conversion from compound names to SMILES, but that may be outside the stated visualization purpose.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      B
      maintenance
      Provides an MCP interface for publication-quality chemical structure and reaction rendering from SMILES/InChI/molblock, with validation and name parsing. Enables AI agents to draw molecules and reactions as images.
      50 PyPI
      MIT
    • A
      license
      C
      quality
      F
      maintenance
      Enables LLM agents to draw and edit ChemDraw reaction schemes, parse ELN exports and LCMS/NMR data, and generate publication-ready CDXML files through grounded chemistry tools.
      35
      3
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables AI assistants to deterministically render accurate 2D organic chemistry structures, reactions, mechanisms, resonance contributors, and stereochemistry directly in chat, with curated JEE presets and fallback resolution.
      1
      MIT