内容
# Illustrator MCP
**使用自然语言控制 Adobe Illustrator — 通过 Claude、ChatGPT、Cursor 或任何 MCP 客户端。**
这是一个 [MCP（模型上下文协议）](https://modelcontextprotocol.io) 服务器，作为 AI 助手和 Adobe Illustrator 之间的桥梁。要求你的助手 *"创建一个 A4 海报，添加一个红色圆角矩形和一个标题"*，它将通过 Illustrator 自己的脚本引擎（ExtendScript）为你驱动 Illustrator。
> 支持 **macOS** 和 **Windows**。Illustrator 必须安装在与服务器相同的机器上。
## 它能做什么？
说这样的话：
- *"创建一个 1080×1080 RGB 文档，并添加标题 'SALE' 为粗体橙色。*"
- *"绘制三个圆圈排成一行，然后将它们对齐到画板中心。*"
- *"将 `~/logo.png` 放在左上角并缩放为 200px 宽。*"
- *"选择所有名为 'badge' 的对象并将其设为蓝色。*"
- *"将当前画板导出为 2 倍透明 PNG 到我的桌面。*"
- *"读取此文档中的所有文本对象并列出它们的内容。*"
它附带 **29 种工具**，涵盖文档、画板、图层、形状、文本、图像、变换、对齐、颜色、选择、导出和 **图像矢量化（自动跟踪）** — 以及一个 **`run_script`** 出口，可以执行 *任何* Illustrator ExtendScript，因此代理永远不会被限制。
**将栅格图像矢量化为可编辑路径。** 一个常见的流程：客户端发送栅格/AI 生成的图像，你需要干净的矢量路径。`illustrator_vectorize_image` 运行 Illustrator 的图像跟踪并将结果扩展为真正的可编辑路径 — 指向文件（或粘贴图像）并返回矢量艺术。最佳用于徽标、扁平艺术、线条艺术和少量颜色的图形；照片级图像会产生许多路径，需要清理。
## 它是如何工作的
```
┌─────────────┐ MCP（stdio） ┌──────────────────┐ ExtendScript ┌──────────────┐
│ Claude / │ ◄────────────► │ illustrator-mcp │ ◄─────────────► │ Adobe │
│ ChatGPT / │ 工具调用 │ 服务器（Node/TS） │ osascript / │ Illustrator │
│ Cursor ... │ │ │ PowerShell COM │ │
└─────────────┘ └──────────────────┘ └──────────────┘
```
- AI 客户端通过 MCP 发送 **工具调用**。
- 服务器将每个调用转换为一个小的 **ExtendScript** 程序。
- 它通过 **AppleScript `do javascript`**（macOS）或 **COM `DoJavaScript`**（Windows）在 Illustrator 中运行该脚本。
- 结果以结构化的 JSON 返回。
由于最终层是 ExtendScript，因此 Illustrator 脚本 API 支持的任何内容都是可达的。
## 要求
- **Adobe Illustrator** 已安装（任何合理最近的版本）并理想情况下正在运行。
- **Node.js 18+**。
- **macOS** 或 **Windows**。
- 一个具有 MCP 功能的客户端（Claude Desktop、Claude Code、Cursor、带有 MCP 的 ChatGPT 桌面版等）。
## 安装
```bash
git clone https://github.com/gherardo200-glitch/illustrator-mcp.git
cd illustrator-mcp
npm install # 同时通过“prepare”脚本构建
npm run build # （仅在跳过安装时构建）
```
这会生成 `dist/index.js`，服务器的入口点。注意其 **绝对路径** — 您需要它来进行客户端配置，例如：
```
/绝对路径/to/illustrator-mcp/dist/index.js
```
## 将其连接到您的 AI 客户端
### Claude Desktop
编辑配置文件：
- **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"illustrator": {
"command": "node",
"args": ["/绝对路径/to/illustrator-mcp/dist/index.js"]
}
}
}
```
重启 Claude Desktop。你应该会看到 Illustrator 工具出现。
### Claude Code
```bash
claude mcp add illustrator -- node /绝对路径/to/illustrator-mcp/dist/index.js
```
… 或提交一个 `.mcp.json` 到你的项目（参见 [`examples/mcp.json`](examples/mcp.json))。
### Cursor
添加到 `~/.cursor/mcp.json`（或项目的 `.cursor/mcp.json`）：
```json
{
"mcpServers": {
"illustrator": {
"command": "node",
"args": ["/绝对路径/to/illustrator-mcp/dist/index.js"]
}
}
}
```
### ChatGPT（桌面版或网页版）
ChatGPT 通过 **连接器**（开发者模式、Plus/Pro 或商业/企业/教育）访问 MCP 服务器 — 它 **不** 直接启动本地 stdio 服务器。
干净的方式是连接此 **本地** 服务器是 OpenAI 的 **安全 MCP 隧道**（`tunnel-client`）：仅限出站，无公共端口。此存储库提供了一个 **HTTP 传输** 来实现这一点 — 运行 `node dist/index.js --http`（监听 `http://127.0.0.1:3000/mcp`）— 但隧道也可以直接驱动 stdio 服务器。
步骤：**[`docs/ATTIVAZIONE.md`](docs/ATTIVAZIONE.md)**（意大利语）· 技术说明：[`docs/CHATGPT.md`](docs/CHATGPT.md)。
### 任何其他 MCP 客户端
两种传输方式，一个代码库：
- **stdio**（默认）— `node dist/index.js`
- **可流式 HTTP** — `node dist/index.js --http`（`PORT` / `HOST` 覆盖默认 `127.0.0.1:3000`，端点 `/mcp`，`/healthz` 用于活动检查）
## 首次运行和权限（macOS）
服务器第一次与 Illustrator 通信时，macOS 会要求权限允许您的终端/应用程序 **控制 Adobe Illustrator**（Apple Events 自动化）。单击 **确定**。
如果您拒绝了它或没有任何反应，请手动启用它：
**系统设置 → 隐私和安全 → 自动化 →** *(您的应用程序：终端 / Claude / Cursor)* → 启用 **Adobe Illustrator**。
**验证连接**，请要求您的助手运行 `illustrator_get_status`（它不会启动 Illustrator，因此是一个安全的第一个调用）。
## 工具
| 领域 | 工具 |
|------|-------|
| **应用程序** | `illustrator_get_status` |
| **文档** | `illustrator_create_document`, `illustrator_open_document`, `illustrator_list_documents`, `illustrator_save_document`, `illustrator_close_document`, `illustrator_export_document` |
| **检查** | `illustrator_get_document_info`, `illustrator_get_selection`, `illustrator_list_layers`, `illustrator_list_artboards` |
| **创建** | `illustrator_create_rectangle`, `illustrator_create_ellipse`, `illustrator_create_line`, `illustrator_create_text`, `illustrator_place_image` |
| **矢量化** | `illustrator_vectorize_image`（图像跟踪 → 可编辑路径） |
| **编辑** | `illustrator_transform_selection`, `illustrator_set_color`, `illustrator_arrange_selection`, `illustrator_align_selection`, `illustrator_delete_selection`, `illustrator_group_selection` |
| **图层** | `illustrator_create_layer`, `illustrator_set_active_layer` |
| **选择** | `illustrator_select_all`, `illustrator_deselect_all`, `illustrator_select_by_name` |
| **功能** | `illustrator_run_script` |
**坐标：** 所有位置和大小均为 **点**（= 72 dpi 像素），从 **活动画板的左上角** 开始测量，**Y 向下增加** — 设计工具的直观约定。（`run_script` 助手从 Illustrator 的原生 Y 上全局系统转换而来。）
**颜色：** 十六进制（`#FF7F00`），常见名称（`red`，`blue`，`green`，...），或 `none`。颜色自动转换为 RGB 或 CMYK 以匹配文档。
### 图像矢量化（两个引擎）
`illustrator_vectorize_image` 支持两个引擎：
- **`vtracer`**（默认）— 开源 [VTracer](https://github.com/visioncortex/vtracer) CLI 生成干净的 SVG，在 Illustrator 中打开为可编辑路径。免费，本地，通常比图像跟踪更干净。**需要 `vtracer` 二进制文件。**
- **`image_trace`** — Illustrator 内置的图像跟踪。无需安装，作为备用。
**安装 VTracer**（一次），选择一个：
- **预构建二进制文件（无需 Rust）：** 从 [发布页面](https://github.com/visioncortex/vtracer/releases) 下载您平台的存档，提取 `vtracer` 二进制文件，并将其放在您的 `PATH` 上（或将 `VTRACER_PATH` 指向它）。在 macOS 上，您可能需要 `xattr -d com.apple.quarantine /path/to/vtracer`。
- **从源代码：** `cargo install vtracer`（需要 Rust 工具链）。
服务器通过 `PATH` 或 `VTRACER_PATH` 环境变量查找 VTracer。如果它丢失，工具会返回清晰的安装说明，您可以切换到 `engine: "image_trace"`。
两个引擎在徽标、扁平艺术、线条艺术和少量颜色的图形上表现最佳；照片级图像会产生许多路径，通常需要手动清理。
### `run_script` 出口
`illustrator_run_script` 运行任意 ExtendScript。代码在一个函数中运行 — 返回一个 JSON 可序列化的值以返回。 Prelude 助手可用：`__doc()`、`__color(hex)`、`__setPos(item, x, y)`、`__itemInfo(item)`、`__abRect()`、`__activeAB(doc)`、`__style(item, opts)`。
```js
// 例如，计算每个文本框架并返回它们的内容
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 };
```
## 安全说明
- 工具带有 MCP **注释**（`readOnlyHint`，`destructiveHint`...），因此客户端可以在破坏性操作（删除、关闭、`run_script`）之前提示。
- `run_script` 很强大：它可以修改/删除艺术作品并触及文件系统。当合适时，请优先使用专门的工具，并审查脚本后再批准它们。
- 服务器仅监听 stdio，从不打开网络端口。
## 故障排除
| 症状 | 修复 |
|--------|-----|
| *"不允许控制 Illustrator"* | 授予自动化权限（参见上文），然后重试。 |
| *"无法访问 Adobe Illustrator"* | 确保 Illustrator 已安装并正在运行。 |
| *"没有打开的文档"* | 使用 `illustrator_create_document` 创建一个或先打开一个文件。 |
| 调用超时 | Illustrator 可能显示了一个模态对话框 — 将其带到前面并关闭它。 |
| 客户端中不显示工具 | 检查配置文件中的绝对路径并重启客户端。 |
## 路线图
- **Illustrator 中的聊天面板**（UXP/CEP）：一个带有聊天框的可停靠面板，您可以在不离开 Illustrator 的情况下与助手交谈。参见 [`docs/IN_APP_CHAT.md`](docs/IN_APP_CHAT.md) 以获取设计、集成计划和成本分解（意大利语）。
- 更多工作流工具（路径查找器、效果、符号、色板、批量导出）。
- ✅ ChatGPT / 远程 MCP 客户端的 HTTP（流式）传输（`--http`）。
欢迎贡献 — 参见 [`CONTRIBUTING.md`](CONTRIBUTING.md)。
## 🇮🇹 快速指南（意大利语）
这是一个连接器，允许 **Claude、ChatGPT 或 Cursor 通过自然语言控制 Adobe Illustrator**（"创建一个 A4 海报，添加一个红色矩形和一个标题"）。
**使用它：**
1. 安装 **Node.js 18+** 并确保您有 **Illustrator**。
2. 在终端中：
```bash
git clone https://github.com/gherardo200-glitch/illustrator-mcp.git
cd illustrator-mcp
npm install
```
3. 复制 `dist/index.js` 的绝对路径。
4. 将其粘贴到您的客户端配置中（参见上面的 **Claude Desktop**）。
5. 重启客户端并请求：*"使用 `illustrator_get_status`"* 以验证其工作。 在 macOS 上，首次使用时授予 **自动化** 权限。
从那里，您可以请求创建文档、形状、文本、对齐、着色、导出 PNG/PDF 等。对于高级操作，有 `illustrator_run_script`，它执行任何 Illustrator 脚本。
---
## License
[MIT](LICENSE) © 2026
