# Illustrator MCP

**Give Claude, ChatGPT, or Cursor the keyboard and mouse for a real, already-open Adobe Illustrator document.**

This is an [MCP (Model Context Protocol)](https://modelcontextprotocol.io) server that bridges an AI assistant and Adobe Illustrator itself, not a generator that hands you a picture and calls it done. Ask your assistant to *"create an A4 poster, add a red rounded rectangle and a headline"* and it drives your actual, running copy of Illustrator through Illustrator's own scripting engine (ExtendScript). What comes out is the same file you can keep editing by hand afterward, layers and all.

**Not just image generation.** Plenty of tools, OpenAI's own image models included, turn a prompt into a vector-looking picture. That picture has no relationship to anything you're working on: no layers, no editable text, no artboards, nothing left to select or nudge. Illustrator MCP is a different kind of thing. It opens, reads, and edits a real Illustrator document while it's sitting open on your screen. Vectorizing a raster image is one of its 29 tools, not the whole project.

> 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."*
- *"Open `campaign.ai`, find the layer called 'Pricing', and change the numbers."*
- *"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."*

Every one of those runs against the Illustrator window that's actually open in
front of you, not a sandbox or a throwaway render. The server ships **29 tools**
covering documents, artboards, layers, shapes, text, images, transforms,
alignment, color, selection, and export, plus a `run_script` escape hatch that
can execute *any* Illustrator ExtendScript, so an agent is never boxed in. Image
vectorization (`illustrator_vectorize_image`, Image Trace under the hood,
expanded into real editable paths) is one of those 29 tools: handy when a client
hands you a raster logo and you need clean paths, but a feature, not the product.

---

## 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

```bash
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`

```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

```bash
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`](examples/mcp.json)).

### Cursor

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

```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`](docs/ATTIVAZIONE.md)** (Italian) ·
technical notes: [`docs/CHATGPT.md`](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). Rejects
  requests with an unrecognized `Host`/`Origin` header (DNS-rebinding
  protection); set `MCP_HTTP_TOKEN` to also require an `X-MCP-Token` header on
  every request. See [Safety notes](#safety-notes).

---

## 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](https://github.com/visioncortex/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](https://github.com/visioncortex/vtracer/releases), 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)`.

```js
// 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 (read, write, or delete any file your OS user can access — ExtendScript's
  `File`/`Folder` API is not sandboxed). Prefer the specialized tools when they
  fit, and **review scripts before approving them**, especially from an AI client
  you don't fully trust.
- **In `--http` mode the server opens a real network port** (default
  `127.0.0.1:3000/mcp`). Anyone who can reach that port can call any tool,
  including `run_script`. The server now rejects requests whose `Host` or
  `Origin` header isn't `127.0.0.1`/`localhost` (plus whatever `HOST` you set)
  on that port, which is the standard defense against **DNS-rebinding
  attacks** (a page on an attacker-controlled domain that briefly resolves to
  `127.0.0.1`, hoping to reach your local server through the browser): the
  browser still sends the attacker's real hostname in `Host`/`Origin`, so it
  never matches the allowlist and gets a `403`. There is still **no
  authentication by default**, so anything else that *can* reach the port
  with a correct `Host` header (another local process, or a device on your
  LAN/internet if you port-forward it) can still call every tool. Set
  `MCP_HTTP_TOKEN` to a random secret to require a matching `X-MCP-Token`
  header on every request (plain requests get `401`); leave it unset and
  behaviour is unchanged. Keep `HOST` at its `127.0.0.1` default, don't
  port-forward or expose `3000` on your LAN/internet, only run `--http` mode
  while you're actively using it, and only use OpenAI's outbound-only Secure
  MCP Tunnel to reach it (see [`docs/CHATGPT.md`](docs/CHATGPT.md); note the
  tunnel client doesn't document a way to attach a custom header today, so
  `MCP_HTTP_TOKEN` and the ChatGPT tunnel may not combine unless you add a
  small local proxy that injects it). stdio mode (the default, used by Claude/
  Cursor) does not open a network port and is not affected.

---

## 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`](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`](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"). Non è un generatore di immagini vettoriali: lavora
dentro un documento Illustrator vero, già aperto sul tuo schermo, che resta
modificabile a mano dopo. La vettorizzazione di un'immagine raster è solo uno dei
29 tool disponibili.

**Per usarlo:**

1. Installa **Node.js 18+** e assicurati di avere **Illustrator**.
2. Nel terminale:
   ```bash
   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](LICENSE) © 2026