# Higgsfield Illustrator MCP

Local MCP server for inspecting and editing Adobe Illustrator documents. Supports
artboards, layers, paths, Bezier curves, shapes, groups, typography and AI/SVG/PNG
output.

## Requirements

- Node.js 24 or later.
- Adobe Illustrator installed on the same computer as the MCP client.
- Tested on macOS with Illustrator 30.8.1. Windows support is experimental.

## Installation

```sh
npm install --global @higgsfield_org/illustrator-mcp
fnf-illustrator doctor
fnf-illustrator config
```

Add the server entry printed by `config` to your MCP client's configuration,
preserving existing entries. It uses absolute Node and server paths. Reconnect
the client after registration. `config` does not change client settings itself.

Open Illustrator, then check the connection:

```sh
fnf-illustrator probe
```

On macOS, allow Automation access for the application launching the MCP. No Adobe
panel or extension is required. The stdio executable is `fnf-illustrator-mcp`.

## Tools

| Tool                 | Purpose                                                      |
| -------------------- | ------------------------------------------------------------ |
| `ai_document_info`   | Inspect the active document.                                 |
| `ai_catalog`         | List 45 operations and retrieve exact argument schemas.      |
| `ai_do`              | Execute a catalog operation.                                 |
| `ai_preview`         | Return an artboard image preview.                            |
| `ai_guide`           | Read editing and targeting instructions.                     |
| `ai_get_skill`       | Index and read bundled Illustrator workflows and references. |
| `ai_get_skill_asset` | Resolve a bundled asset or script to a verified local path.  |
| `ai_status`          | Inspect local connection state.                              |

Call `ai_get_skill` without arguments to discover any specialized workflows in
the installed version; an empty index means use `ai_guide`. Asset paths returned
by `ai_get_skill_asset` exist on this computer only. Reading a skill does not
prove Illustrator is connected or that every described operation is supported.

Use exact unique document names and item UUIDs from inspection results.
Coordinates are points; artboard bounds are `[left, top, right, bottom]`.
Typography applies to entire text frames. Save/export requires a new absolute
path. Save As and SVG export can change document identity; refresh it before
subsequent calls. Set `ADOBE_MCP_READONLY=1` in the server environment to disable
mutations, exports and previews.

## Troubleshooting and limits

`doctor` checks local prerequisites; `probe` reads Illustrator. Verify a tool call
in the MCP client after registration. Calls are serialized across clients.
`BUSY` means another call or an unresolved prior call owns the lock.

`OS_SCRIPT_NOT_STARTED` means an OS permission or executable problem prevented
dispatch; correct it and retry. A timeout may leave a script running. Inspect
Illustrator before recovering `~/.higgsfield-adobe/illustrator.lock`; do not remove
it while execution is active or blindly repeat edits. Native errors may leave
partial changes.

Gradient meshes, clipping masks, symbols, advanced appearance effects, rich-text
ranges and general undo transactions are not supported. Windows uses PowerShell/COM;
organization policy may restrict script execution.