Illustrator MCP

Control Adobe Illustrator with natural language — from Claude, ChatGPT, Cursor, or any MCP client.

This is an MCP (Model Context Protocol) server that acts as a bridge between an AI assistant and Adobe Illustrator. Ask your assistant to "create an A4 poster, add a red rounded rectangle and a headline" and it drives Illustrator for you through Illustrator's own scripting engine (ExtendScript).

Works on macOS and Windows. Illustrator must be installed on the same machine as the server.

---

What can it do?

Say things like:

• "Create a 1080×1080 RGB document and add the title 'SALE' in bold orange."
• "Draw three circles in a row, then align them to the center of the artboard."
• "Place ~/logo.png in the top-left corner and scale it to 200px wide."
• "Select everything named 'badge' and make it blue."
• "Export the current artboard as a 2x transparent PNG to my Desktop."
• "Read all the text objects in this document and list their contents."

It ships with 29 tools covering documents, artboards, layers, shapes, text, images, transforms, alignment, color, selection, export, and image vectorization (auto-trace) — plus a run_script escape hatch that can execute any Illustrator ExtendScript, so an agent is never boxed in.

Vectorize a raster image → editable paths. A common workflow: a client sends a raster/AI-generated image and you need clean vector paths. illustrator_vectorize_image runs Illustrator's Image Trace and expands the result into real, editable paths — point it at a file (or paste the image) and get vector art back. Best on logos, flat art, line art, and few-color graphics; photorealistic images produce many paths and need cleanup.

---

How it works

┌─────────────┐   MCP (stdio)   ┌──────────────────┐   ExtendScript   ┌──────────────┐
│ Claude /    │ ◄────────────► │ illustrator-mcp   │ ◄─────────────► │  Adobe        │
│ ChatGPT /   │   tool calls    │ server (Node/TS)  │  osascript /     │  Illustrator  │
│ Cursor ...  │                 │                   │  PowerShell COM  │              │
└─────────────┘                 └──────────────────┘                  └──────────────┘

• The AI client sends tool calls over MCP.
• The server turns each call into a small ExtendScript program.
• It runs that script inside Illustrator via AppleScript do javascript (macOS) or COM DoJavaScript (Windows).
• Results come back as structured JSON.

Because the final layer is ExtendScript, anything the Illustrator scripting API supports is reachable.

---

Requirements

• Adobe Illustrator installed (any reasonably recent version) and, ideally, running.
• Node.js 18+.
• macOS or Windows.
• An MCP-capable client (Claude Desktop, Claude Code, Cursor, ChatGPT desktop with MCP, …).

---

Install

git clone https://github.com/gherardo200-glitch/illustrator-mcp.git
cd illustrator-mcp
npm install        # also builds via the "prepare" script
npm run build      # (only needed if you skip install-time build)

This produces dist/index.js, the server entry point. Note its absolute path — you'll need it for the client config, e.g.:

/absolute/path/to/illustrator-mcp/dist/index.js

---

Connect it to your AI client

Claude Desktop

Edit the config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "illustrator": {
      "command": "node",
      "args": ["/absolute/path/to/illustrator-mcp/dist/index.js"]
    }
  }
}

Restart Claude Desktop. You should see the Illustrator tools appear.

Claude Code

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

…or commit a .mcp.json to your project (see examples/mcp.json).

Cursor

Add to ~/.cursor/mcp.json (or the project's .cursor/mcp.json):

{
  "mcpServers": {
    "illustrator": {
      "command": "node",
      "args": ["/absolute/path/to/illustrator-mcp/dist/index.js"]
    }
  }
}

ChatGPT (desktop or web)

ChatGPT reaches MCP servers through connectors (Developer Mode, Plus/Pro or Business/Enterprise/Edu) — it does not launch a local stdio server directly. The clean way to connect this local server is OpenAI's Secure MCP Tunnel (tunnel-client): outbound-only, no public port. This repo ships an HTTP transport for exactly this — run node dist/index.js --http (listens on http://127.0.0.1:3000/mcp) — though the tunnel can also drive the stdio server directly.

Step-by-step: docs/ATTIVAZIONE.md (Italian) · technical notes: docs/CHATGPT.md.

Any other MCP client

Two transports, one codebase:

• stdio (default) — node dist/index.js
• Streamable HTTP — node dist/index.js --http (PORT / HOST override the default 127.0.0.1:3000, endpoint /mcp, /healthz for liveness)

---

First run & permissions (macOS)

The first time the server talks to Illustrator, macOS asks permission to let your terminal/app control Adobe Illustrator (Apple Events automation). Click OK.

If you denied it or nothing happens, enable it manually: System Settings → Privacy & Security → Automation → (your app: Terminal / Claude / Cursor) → enable Adobe Illustrator.

Verify the connection by asking your assistant to run illustrator_get_status (it does not launch Illustrator, so it's a safe first call).

---

Tools

Area	Tools
App	illustrator_get_status
Documents	illustrator_create_document, illustrator_open_document, illustrator_list_documents, illustrator_save_document, illustrator_close_document, illustrator_export_document
Inspect	illustrator_get_document_info, illustrator_get_selection, illustrator_list_layers, illustrator_list_artboards
Create	illustrator_create_rectangle, illustrator_create_ellipse, illustrator_create_line, illustrator_create_text, illustrator_place_image
Vectorize	illustrator_vectorize_image (Image Trace → editable paths)
Edit	illustrator_transform_selection, illustrator_set_color, illustrator_arrange_selection, illustrator_align_selection, illustrator_delete_selection, illustrator_group_selection
Layers	illustrator_create_layer, illustrator_set_active_layer
Selection	illustrator_select_all, illustrator_deselect_all, illustrator_select_by_name
Power	illustrator_run_script

Coordinates: all positions and sizes are in points (= pixels at 72 dpi), measured from the top-left of the active artboard, with Y increasing downward — the intuitive convention for design tools. (The run_script helpers convert from Illustrator's native Y-up global system.)

Colors: hex (#FF7F00), a common name (red, blue, green, …), or none. Colors are automatically converted to RGB or CMYK to match the document.

Image vectorization (two engines)

illustrator_vectorize_image supports two engines:

• vtracer (default) — the open-source VTracer CLI produces a clean SVG that is opened in Illustrator as editable paths. Free, local, and usually cleaner than Image Trace. Requires the vtracer binary.
• image_trace — Illustrator's built-in Image Trace. No install, kept as a fallback.

Install VTracer (once), pick one:

• Prebuilt binary (no Rust needed): download your platform's archive from the releases page, extract the vtracer binary, and put it on your PATH (or point VTRACER_PATH at it). On macOS you may need xattr -d com.apple.quarantine /path/to/vtracer.
• From source: cargo install vtracer (needs the Rust toolchain).

The server finds VTracer via PATH or the VTRACER_PATH environment variable. If it's missing, the tool returns clear install instructions and you can fall back to engine: "image_trace".

Both engines are best on logos, flat art, line art, and few-color graphics; photorealistic images produce many paths and usually need manual cleanup.

The run_script escape hatch

illustrator_run_script runs arbitrary ExtendScript. The code runs inside a function — return a JSON-serializable value to get it back. Prelude helpers are available: __doc(), __color(hex), __setPos(item, x, y), __itemInfo(item), __abRect(), __activeAB(doc), __style(item, opts).

// e.g. count every text frame and return their contents
var d = __doc();
var out = [];
for (var i = 0; i < d.textFrames.length; i++) out.push(d.textFrames[i].contents);
return { count: out.length, texts: out };

---

Safety notes

• Tools carry MCP annotations (readOnlyHint, destructiveHint, …) so clients can prompt before destructive actions (delete, close, run_script).
• run_script is powerful: it can modify/delete artwork and touch the file system. Prefer the specialized tools when they fit, and review scripts before approving them.
• The server only listens on stdio and never opens a network port.

---

Troubleshooting

Symptom	Fix
"Not authorized to control Illustrator"	Grant Automation permission (see above), then retry.
"Could not reach Adobe Illustrator"	Make sure Illustrator is installed and running.
"No document is open"	Create one with illustrator_create_document or open a file first.
Calls time out	Illustrator may be showing a modal dialog — bring it to the front and dismiss it.
Tools don't appear in the client	Check the absolute path in the config and restart the client.

---

Roadmap

• Chat panel inside Illustrator (UXP/CEP): a dockable panel with a chat box so you can talk to the assistant without leaving Illustrator. See docs/IN_APP_CHAT.md for the design, integration plan, and a cost breakdown (in Italian).
• More workflow tools (pathfinder, effects, symbols, swatches, batch export).
• ✅ HTTP (Streamable) transport for ChatGPT / remote MCP clients (--http).

Contributions welcome — see CONTRIBUTING.md.

---

🇮🇹 Guida rapida (Italiano)

Questo è un connettore che permette a Claude, ChatGPT o Cursor di comandare Adobe Illustrator parlandogli in linguaggio naturale ("crea un poster A4, aggiungi un rettangolo rosso e un titolo").

Per usarlo:

1. Installa Node.js 18+ e assicurati di avere Illustrator.
2. Nel terminale:

   git clone https://github.com/gherardo200-glitch/illustrator-mcp.git
   cd illustrator-mcp
   npm install
   

3. Copia il percorso assoluto di dist/index.js.
4. Incollalo nella configurazione del tuo client (vedi Claude Desktop sopra).
5. Riavvia il client e chiedi: "usa illustrator_get_status" per verificare che funzioni. Su macOS, al primo utilizzo concedi il permesso di automazione.

Da lì in poi puoi chiedere di creare documenti, forme, testi, allineare, colorare, esportare PNG/PDF e altro. Per operazioni avanzate c'è illustrator_run_script, che esegue qualsiasi script di Illustrator.

---

License

MIT © 2026