# Illustrator MCP

An MCP server that lets AI assistants control Adobe Illustrator through a CEP panel.
Version 3.0.0 supports structured artwork edits, ExtendScript, document management,
visual previews, PNG/JPG export, and SVG path import.

## Requirements

- Python 3.10 or newer.
- Adobe Illustrator on Windows or macOS. The panel manifest permits Illustrator 25.0+;
  this is an installation range, not a verified compatibility guarantee. Compatibility
  across that range and both platforms has not yet been validated.
- Node.js and npm compatible with Vite 6 to build the panel.
- An MCP client supporting stdio.

## Installation

Download or clone this repository, then open a terminal in its root directory.

```sh
python -m venv .venv
```

Activate the environment with `.venv\Scripts\activate` on Windows or
`source .venv/bin/activate` on macOS, then install:

```sh
python -m pip install -e ".[geometry]"
cd cep-extension
npm ci
npm run typecheck
npm run build
node validate-panel.mjs
cd ..
```

The optional `geometry` extra enables boolean path operations. Use
`python -m pip install -e .` if you do not need it.

On Windows, run `install-cep.bat` from an Administrator terminal.
On macOS, run `bash install-cep.sh`.
The installers link the panel into Adobe's CEP extensions directory and enable
CEP debug mode. Keep the checkout at its installed location.

Restart Illustrator and open **Window > Extensions > MCP Control**.

## MCP client configuration

Add the following server definition to your client's MCP configuration, replacing
the interpreter path with the absolute path to your installed virtual environment:

```json
{
  "mcpServers": {
    "illustrator": {
      "command": "C:/path/to/Illustrator_MCP/.venv/Scripts/python.exe",
      "args": ["-B", "-m", "illustrator_mcp.server"],
      "env": {
        "WS_HOST": "127.0.0.1",
        "WS_PORT": "8081",
        "TIMEOUT": "30"
      }
    }
  }
}
```

On macOS use `/absolute/path/to/Illustrator_MCP/.venv/bin/python`.
Restart the client's integration and connect the panel. The Python server owns
the WebSocket bridge; only one client should start it at a time.
The bundled panel uses the fixed endpoint `ws://127.0.0.1:8081`. Keep `WS_HOST`
and `WS_PORT` at these values. To change the port, also edit `MCP_ENDPOINT` in
`cep-extension/src/connection/ConnectionController.ts`, rebuild, and reload the panel.
Changing only the server configuration will prevent the panel from connecting.

## Distribution and versions

This source release pairs server 3.0.0 with CEP panel 1.0.2. Their version numbers
are independent. The source archive includes panel sources and installers; build
the panel before installing it. A Python wheel contains the server and its runtime
resources only; obtain the matching CEP panel separately from this source release.

## Usage

Start with `illustrator_connection_status` using `{"params":{"probe":true}}`.
Open or create a document, then ask your assistant to inspect it before editing.

- `illustrator_document`: create, open, list, activate, save, or close documents.
- `illustrator_observe`: inspect previews and artwork context.
- `illustrator_get_document` and `illustrator_query_items`: inspect structure and targets.
- `illustrator_execute_task`: execute structured batches of artwork operations.
- `illustrator_execute_script`: execute ExtendScript with reusable libraries.
- `illustrator_place_file` and `illustrator_set_reference`: place assets and references.
- `illustrator_path_boolean` and `illustrator_path_import_svg`: work with vector paths.
- `illustrator_preflight_check`: check artwork before delivery.
- `illustrator_export_document`: export PNG or JPG.
- `illustrator_history`: undo, redo, and manage checkpoints.
- `illustrator_job_status`: inspect or reconcile an uncertain job.

The server exposes operation descriptions through `illustrator://ops`, scripting
guidance through `illustrator://reference/extendscript`, and library help through
`illustrator://reference/libraries` and `illustrator://libraries/{name}`.
Files under `illustrator_mcp/resources/docs/` supply these runtime references.

## Limitations and troubleshooting

This is alpha software. Native SVG/PDF export is currently unavailable; PNG/JPG
export and SVG path import are supported. Save your work before automated edits.

A timeout does not mean Illustrator stopped executing. Inspect and reconcile the
job before retrying an uncertain edit. Export supports `overwrite="fail"` and
`overwrite="version"` when replacement is unwanted.

If the panel does not connect, check that the client started the server and that
its WebSocket port matches the panel. Stop the previous client integration before
switching clients. For panel updates, rebuild the extension, reload the panel,
and restart the MCP server. Server diagnostics are written to stderr.

## License

MIT; see [LICENSE](LICENSE). Bundled third-party files retain their own notices.