Illustrator Figure MCP

Rebuild scientific figures as editable Adobe Illustrator artwork, and prove the result is structurally correct.

macOS only (Illustrator is macOS/Windows; this uses osascript → do javascript). Requires Adobe Illustrator and Claude Code.

Why this exists

Plenty of MCP servers can draw in Illustrator. They give a model hands but no eyes: nothing checks whether the thing it just drew is right. So the model draws, reports success, and the figure has a label overflowing its box, an arrow ending in the middle of an unrelated rectangle, and three "aligned" panels that are 3pt out.

The valuable part is not the drawing. It is the validate-and-repair loop, on two channels that check different things:

Geometry is proved. Similarity is judged. Neither alone is enough — a traced figure passes every geometric check while being entirely non-editable, and a good-looking render says nothing about structure.

audit_figure returning passed: true means no hard geometric failure. It does not mean the figure is correct.

Related MCP server: Illustrator MCP Vectorizer

Reconstruct, never trace

Tracing preserves appearance and destroys semantics, which is the whole point of rebuilding a figure. Three defences make the shortcut hard to take:

• Semantic tagging at creation. Every object gets a UUID and a semantic type as it is made, so the auditor can tell constructed objects from foreign geometry.

• trace-signature. Image Trace's expandTracing() drops one untagged group holding a pile of untagged paths; that, dense untagged paths, and bulk geometry exceeding the declared draw log are all hard failures.

• The raster gate. place_image refuses any placement that is not provably irreducible.

The raster gate

Every retained image must declare all five, and they are validated, not just recorded:

Enforcement is on the creation path, not in the auditor: an auditor-only check is bypassed by not auditing.

Connectors

Illustrator has no connector primitive. An arrow is a PathItem and has no relationship to the box it points at — move the box and the arrow stays behind, silently wrong.

add_connector records the binding (source, target, attachment sites) on the path. reflow_connectors re-solves the geometry from the objects' current bounds. audit_figure reports connector-detached when the drawn path no longer agrees with its binding.

Routing is straight, orthogonal, or curved — a bezier that leaves and arrives perpendicular to the attachment edges, which is the standard pathway-diagram look and makes arrowheads read as pointing squarely into their target. The auditor samples the actual curve rather than the chord between anchors, so it checks where the ink is.

Any operation that moves or resizes a connected object must be followed by reflow_connectors. Arrowheads are drawn as filled triangles, since Illustrator exposes no arrowhead property to scripting.

→ Full usage guide — install, core rules, tool reference, two worked examples, and how to read an audit report.

Install

npm install && npm run build

Add it to Claude Code:

claude mcp add illustrator-figure -- node /absolute/path/to/IllustratorFigureMCP/dist/index.js

Grant Automation permission the first time a tool runs: System Settings → Privacy & Security → Automation → Claude → Adobe Illustrator.

Install the four role skills:

cp -R skills/* ~/.claude/skills/

The four roles

Ask Claude to "recreate this figure in Illustrator" with a reference image, and recreate-scientific-figure coordinates the loop:

Each region must pass before the next begins; then the whole figure runs the same loop.

Tools added by this fork

Plus the raster gate on place_image, and semantic tagging on every create_* tool. The remaining 66 tools are upstream's (71 in total).

draw_sequence is the one to reach for: nine objects — boxes, area-text labels, two bound connectors — build and audit in roughly 750ms, where one call per object would be nine round trips.

Documentation

Development

npm test        # 245 tests, runs on any platform

The ported geometry is pure ES3, so the .jsx modules are loaded into a VM and the Liang–Barsky and segment-crossing maths is tested without Illustrator. Anything that touches Illustrator must be tested on macOS with it running — see CLAUDE.md for the constraints that are easy to break (ES3, UUID-before-metadata ordering, pageItems snapshotting).

Credits

• Tool layer forked from ie3jp/illustrator-mcp-server (MIT) — transport, JSX runner, UUID identity, note metadata, and 63 Illustrator tools. See LICENSE.

• The two-channel validation loop, the audit taxonomy, and the four-role protocol are ported from icebird1998/scientific-illustrator, which implements them for draw.io, PowerPoint, and WPS. The maths is backend-neutral; the object model is not.

Not affiliated with Adobe.