illustrator-bridge
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
illustrator-bridge
從需求表單/截圖批次產生 Illustrator 的工作區域與名稱。搭配 Claude Code 使用。
Claude Code ──stdio── MCP server ──AppleScript── Illustrator ──ExtendScript── 工作區域不需要安裝任何 Illustrator 外掛,用的是 Illustrator 內建的 do javascript,
所以 Illustrator 的 DOM 功能 100% 可用(UXP 面板反而做不到這件事)。
安裝
需求:macOS、Adobe Illustrator、Node.js 18 以上、Claude Code。
git clone https://github.com/groundfic/illustrator-mcp-bridge.git ~/illustrator-bridge
cd ~/illustrator-bridge
npm install
claude mcp add --scope user illustrator-bridge -- node ~/illustrator-bridge/src/index.js裝好後開一個新的 Claude Code 對話,請它跑 connection_status。第一次執行 macOS 會問自動化權限,要允許終端機控制 Adobe Illustrator。
skill/ 是給 Claude 讀的工作手冊(踩過的坑、印刷判斷)。要用的話複製到 ~/.claude/skills/illustrator/:
mkdir -p ~/.claude/skills/illustrator && cp -R skill/ ~/.claude/skills/illustrator/Related MCP server: Illustrator MCP
用法
在 Claude Code 裡直接講,例如:
[貼上報價單截圖] 照這張表建工作區域
Claude 會判讀出「要做哪些格式、各幾件」,先用 dryRun 試算給你確認,
確認後才真的建立。也可以直接下指令:
建工作區域:名片 90×54 兩面、A4 傳單 2 款、IG 貼文 1080px 3 張,出血 3mm
工具
工具 | 用途 | 會改文件? |
| 檢查 Illustrator 有沒有開、通道通不通 | 否 |
| 文件狀態:存檔路徑、未存修改、色彩模式、尺規單位、工作區域;圖層、色票、特別色、連結圖、字型、文字的摘要或完整清單 | 否 |
| 某個工作區域上的物件:類型、名稱、圖層、鎖定/隱藏、以工作區域左上角為原點的 mm 座標 | 否 |
| 把工作區域匯出成圖片直接給 Claude 看,可裁切局部 | 否(見下) |
| 一鍵印前檢查:色彩、文字、連結圖、出血、細線、疊印、雜物,回問題清單 | 否 |
| 列出登錄的現成 .jsx:用途、能否無介面執行、參數、驗證狀態 | 否 |
| 執行現成的 .jsx(登錄名稱或路徑),有介面的拒絕執行 | 看指令碼(會改的先備份) |
| 主力。依規格批次建立,網格排列、自動命名 | 是(附加時先備份) |
| 依索引改名 | 是(先備份) |
| 解析卡片欄位,做成 CSV 範本 | 否 |
| 照表格批次複製卡片 | 是(先備份) |
| 逃生門:跑任意 ExtendScript | 可能(預設先備份) |
安全機制(1.1.0)
對話框鎖死防護:每次執行期間把
app.userInteractionLevel設成DONTDISPLAYALERTS(缺字型、連結遺失這類 Illustrator 自己的警告不會跳出來卡住通道),結束後還原原值,腳本丟例外也一樣。execute_jsx的程式碼若含alert(/confirm(/prompt(/new Window(/openDialog(等, 送出前就拒絕(註解裡寫到不算)。改動前自動備份:
create_artboards(附加到既有文件時)、rename_artboards、card_build、execute_jsx、run_script(登錄為會改文件的指令碼,1.2.0)執行前,把作用中文件磁碟上的檔案複製到~/Library/Application Support/illustrator-bridge/backup/<時間>-<原檔名>,回傳的backup欄位是路徑。⚠️ 備份的是上次存檔時的狀態,Illustrator 裡還沒存檔的修改救不回來。
從沒存過檔的新文件不備份、不報錯;超過 500MB 略過並回 warning。
同一個檔 10 分鐘內只備份一次(檔案自上次備份後沒變也沿用);啟動時清掉 30 天以上的舊備份。
純讀取的
execute_jsx請傳backup: false。時間用本地時間、冒號換成連字號(例
2026-11-15T14-03-22-客戶檔.ai),Finder 才不會顯示成斜線。備份位置可用環境變數
AI_BRIDGE_BACKUP_DIR改。
截圖不改文件:
exportFile只認作用中的工作區域,切過去後一定切回; 實測exportFile會把文件標成「已修改」(它把匯出設定記進文件),所以匯出前若是已存檔狀態,匯出後把saved設回 true。 存檔路徑不變(不用saveAs)。
get_document_info
預設回摘要:固定欄位+每類的數量與前 5 筆。要完整清單給 sections(artboards layers swatches spots
links fonts text)與 limit(預設 200);給了 sections 時沒列到的類別只回數量,fonts 不掃描。
fullName:存檔路徑,從沒存過檔為null;hasUnsavedChanges=!saved。連結圖:
effectivePPI由置入縮放算出(boundingBox是像素座標、matrix是縮放); 連結檔的色彩空間用 macOS 內建sips讀;遺失連結 DOM 讀不到路徑,改從 XMP 連結清單比對出missingPaths。字型只從文件裡的文字讀,絕不碰
app.textFonts。textRanges是逐字的,每字成本隨文字框數增加 (實測 300 框約 15µs/字、1500 框約 145µs/字),所以設探測預算,超過的文字框改等距抽樣,fonts.scan.complete會標示。實測:1500 個文字框的文件摘要約 0.7 秒;
sections:["fonts"]約 2.5 秒。
get_artboard_items
工作區域不是容器,這裡用 artboardRect 與物件 geometricBounds 幾何比對(兩者 Y 向上為正、top > bottom),
輸出換成工作區域左上角原點、Y 向下、mm 的 x,y,w,h,可直接當 take_snapshot 的 crop。
mode:intersect(預設,重疊才算,只貼齊邊緣不算)/contain(完全在內);partial: true表示超出工作區域。只列最上層物件;
expandGroups: true展開一層。剪裁群組用遮色片範圍計算(不然被遮掉的部分會讓它看起來很大)。includeLocked/includeHidden預設 true(列出並標示),鎖定/隱藏包含所在圖層的狀態。每筆附
uuid,在execute_jsx可用app.activeDocument.getPageItemFromUuid(uuid)抓同一個物件。最多掃 20000 個物件;實測 3000 個物件約 0.3 秒。
take_snapshot
artboardIndex(預設作用中)、maxSize(長邊像素上限,預設 1200,最大 4000)、crop(mm,工作區域左上角起算)、
format(jpg 預設/png)。裁切時以裁切範圍長邊 = maxSize 放大匯出(倍率上限 776%、整張匯出長邊上限 8000px),
再用 sips 裁切;暫存檔讀成 base64 後刪掉。實測簡單 A4:jpg 1200px 約 0.45 秒、23KB;2400px 約 0.6 秒、70KB。
Illustrator 會把匯出範圍對齊像素格,長邊可能比 maxSize 少 1px。
check_document(1.2.0)
只讀不改(不碰選取、不切工作區域,回傳 state.unchanged 確認),回 {doc, elapsedMs, summary, report}。
report 每類有 level、count、前 limit 筆 items(工作區域名稱、圖層、物件名稱或類型、mm 座標、uuid),依嚴重度排序。
檢查 | 類別(level) |
|
|
|
|
|
|
|
|
|
|
|
|
|
|
參數:
only、limit(預設 10)、bleed(mm,預設 3,0不查)、bleedStrict(預設 false;true 時也報出血不足)、minPPI(預設 300)、minStroke(pt,預設 0.25)。隱藏、不列印圖層的物件不查色彩、筆畫、疊印、出血;遺失連結照報。
文字只看整框的字元屬性(不逐字),絕不碰
app.textFonts。符號、外掛物件(即時效果)、網格、圖表內部不檢查,summary.notCheckedTypes會列出。Illustrator 會把 CMYK 文件裡指定的 RGB 填色、以 RGB 定義的色票自動轉成 CMYK,嵌入 RGB 圖也會轉;實務上
rgbImages來自連結的 RGB 圖(sips讀檔頭)。上限:走訪 50000 個物件或 90 秒,超過在
summary.truncated標示。實測 3000 個物件約 0.4 秒(引擎內 0.2 秒)、回傳約 6KB。
list_scripts/run_script(1.2.0)
登錄檔是範例:
scripts/registry.json列的 .jsx(grid-guides、StampTexture、GlyphParts、CardTable、CreateExpandedArtboards、print-prepress)是作者自己的指令碼,沒有隨這個 repo 附上。 請把登錄檔改成你自己的 .jsx,或直接給run_script一個path。tests/scripts.js、tests/cardtable*.js需要那些指令碼才跑得起來。
登錄檔 scripts/registry.json:每支指令碼的路徑(~ 開頭)、用途、headless、判定依據、參數與預設值、作用對象、會不會改文件、驗證狀態。
名稱 | 指令碼 | 無介面 |
|
| ✅ |
|
| ✅ |
|
| ✅ |
|
| ✅ 照 |
|
| ❌ 只有 ScriptUI |
|
| ✅ |
headless:false一律拒絕(沒送進 Illustrator),回hint請使用者從「檔案 → 指令碼 → 其他指令碼…」執行。沒登錄的檔:原始碼有
alert(/new Window(/檔案對話框/#targetengine就拒絕;確定有無介面模式時帶configGlobal+assumeHeadless:true。#include不支援。參數放進約定的全域變數,跑完一定還原(grid-guides、GlyphParts 不會自己清,留著的話下次從選單執行會跳過對話框)。 專案
_tools那類「前面補var OUT, DOC再跑」的指令碼給vars(在同一個函式範圍宣告)。編碼:不用
$.evalFile。檔案讀進 node(處理 BOM、UTF-16,不是 UTF-8 就報錯)送進引擎 eval,有沒有 BOM 中文都正確。 實測$.evalFile對沒有 BOM 的檔是看開頭猜編碼:開頭就有中文會猜對,前段全是 ASCII 的檔中文會亂碼。指令碼在引擎裡的獨立函式範圍 eval:頂層的
var/function不會蓋到引擎,也不會殘留在$.global。#target行改成註解(行號不變);用到$.fileName的會警告(它指向暫存檔)。同一個行程同時只跑一支;逾時照登錄(60~600 秒,MCP 最長 600)。
命令列(不經 MCP)
bash scripts/run.sh list
bash scripts/run.sh check [參數.json] [逾時秒] # 也可以 bash scripts/check.sh [參數.json]
bash scripts/run.sh grid-guides grid.json
bash scripts/run.sh ~/某處/工具.jsx params.json 300 # 參數檔可放 "_run": {"configGlobal","vars","assumeHeadless","backup","prepressConfig"}輸出 JSON;ok:false 時 exit 1。防護跟 MCP 工具相同,命令列逾時最長 7200 秒。作用對象一樣是作用中文件。
create_artboards 的行為
排列:由左上往右排,滿一列往下。同尺寸自動成一組,換尺寸另起一區(
groupBySize,預設開)。每列幾個:
layout.cols;不給就自動排成接近正方形,上限 8 欄。單位(⚠️ 1.2.1 行為改變):有給
unit照給的;沒給unit時看目標文件的色彩模式:CMYK → mm、RGB → px。 附加到既有文件看那份文件的documentColorSpace;新建文件看這次的documentColorSpace(沒給是 CMYK)。 尺寸、gutter、groupGap、bleed都跟著這個單位;layout.unit有給時間距仍以它為準,單項的items[].unit只管該項尺寸。 回傳(dryRun也是)一定有unitUsed、unitSource(例如"文件是 RGB(沒給 unit:RGB 用 px)")、gapUnit, 有出血時還有bleedUnit,執行前先看單位對不對。 印刷案在 RGB 文件裡工作時要明確給unit: "mm",不然90×54會變成 90×54px。get_document_info/get_artboard_items/check_document的回傳單位不變(mm)。間距:
layout.gutter沒給時 10mm,群組之間layout.groupGap沒給時 20mm(不論單位)。 有給數值時單位跟著layout.unit> 最外層unit> 上面的預設單位(1.1.0 起;舊版一律 mm)。 例如unit: "px"時gutter: 40是 40px。要固定用 mm 設layout.unit: "mm"。接在哪:已有文件時接在現有工作區域下方,不會壓到既有內容;沒有文件則自動新建(預設 CMYK)。
命名:
count > 1時自動變名稱-01、名稱-02;可用nameTemplate自訂({name}{n}{nn})。重名:自動加
(2)(3)區隔(dedupeNames)。名稱原樣保留:全形括號、全形空白、
/ : \ * ? " < > |、emoji 都照收(Illustrator 30.8 實測)。 只有換行/tab 換成空白、控制字元移除(NUL 會讓 Illustrator 截斷名稱)。出血:
bleed: 3會在鎖定圖層「出血參考」畫出血框(洋紅細線)。單位跟著最外層unit(沒給就是上面的預設單位)。可用單位:
mmcmptpxinq(級/齒,1Q = 0.25mm);Illustrator 裡 1px=1pt。
邊界處理
單邊超過 16383pt(約 5779mm)或小於 1pt → 跳過該項並在
warnings說明,其餘照建。一份文件超過 1000 個工作區域 → 整批擋下並說明。
名稱長度不截斷(舊版以為上限 100 字,實測 130 字照收)。空名稱在
rename_artboards會被拒絕(Illustrator 會改回預設名)。
疑難排解
「沒有自動化權限」 → 系統設定 → 隱私權與安全性 → 自動化 → 勾選你的終端機底下的「Adobe Illustrator」。
執行卡住不回應 → Illustrator 有對話框擋著。切過去關掉即可。
1.1.0 起 Illustrator 自己的警告會被關掉、execute_jsx 裡的 alert() 等會在送出前被擋下;
但 app.executeMenuCommand() 開的選單對話框(例如文件設定)仍擋不住,別在腳本裡叫。
改壞了要救 → ~/Library/Application Support/illustrator-bridge/backup/ 找同名檔(時間在檔名最前面)。
只有上次存檔的內容。
指到錯的 Illustrator 版本 → 多版本並存時設環境變數:
AI_BRIDGE_APP_ID=com.adobe.illustrator node src/index.js想看實際送進去的 jsx → AI_BRIDGE_KEEP_TMP=1,暫存檔會留在 $TMPDIR/illustrator-bridge/。
台灣印刷常見尺寸(mm)
名片 90×54|明信片 148×100|A4 210×297|A3 297×420|B5 182×257|菊八開 195×270
開發
npm install
node tests/unit.js # 不需要 Illustrator:對話框偵測、備份去重與清理、截圖換算、名稱清洗、檢查分類、指令碼登錄與編碼
node tests/smoke.js # 會在 Illustrator 開新文件實測,跑完關掉,不動你正開著的檔需要 Illustrator 的測試(都在自己新建的暫存文件上做,跑完關掉、作用中文件切回原本那份):
測試 | 內容 |
| userInteractionLevel 設定與還原、alert 擋下 |
| 備份、去重、 |
| 截圖尺寸、裁切、PNG、 |
| 圖層/色票/特別色/連結(含遺失)/字型/文字、大文件耗時 |
| 幾何比對、座標換算、鎖定/隱藏、群組展開、剪裁群組 |
| 全形字元名稱、px 間距(走 MCP 通道) |
| 沒給 unit 時的預設單位:既有/新建 × CMYK/RGB × 有沒有給 unit,含間距、出血、回傳的 unitUsed/unitSource |
| 印前檢查:做壞的文件逐項抓、乾淨文件零誤報、RGB 文件、參數、3000 物件耗時 |
| run_script:中文編碼(對照 |
| 新工具走 MCP 通道的整合測試 |
| 卡片掃描與生成 |
需要「已存檔的文件」的測試(與測試圖檔、測試用 .jsx)會存到 AI_TEST_DIR(預設 $TMPDIR/illustrator-bridge-test/)。
src/jsx/engine.jsx 是實際跑在 Illustrator 裡的引擎,
src/runner.js 負責組檔與 osascript 通道,src/index.js 只做 MCP 的殼;
src/check.js(印前檢查的連結分類與摘要)、src/scripts.js(指令碼登錄與執行)MCP 與命令列共用。
⚠️ 產生的暫存 jsx 必須帶 UTF-8 BOM,否則 ExtendScript 會把中文讀成亂碼。
回傳值則把非 ASCII 全轉成 \uXXXX,避開 AppleScript ↔ stdout 的編碼問題。
授權
MIT,見 LICENSE。
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Use your Mac, Windows or Linux computer from ChatGPT, Claude or Codex: files, commands, documents.
Work on your own computers from Claude or ChatGPT: run commands, edit and search files.
Build, validate, test-run and publish AIOS workflows from Claude Code, Codex, Cursor or VS Code.
Marketo MCP server for AI. 130 tools to operate Marketo from Claude, Cursor, or ChatGPT.
Related MCP Servers
- FlicenseNot gradedqualityDmaintenanceEnables AI agents to automate Adobe Illustrator, converting bitmap artwork into editable .ai files, running ExtendScript, and capturing the Illustrator window for visual QA.1-
- AlicenseAqualityCmaintenanceAn MCP server that lets AI assistants like Claude control Adobe Illustrator through natural language by executing ExtendScript code and providing document state inspection.127MIT
- FlicenseNot gradedqualityDmaintenanceEnables bots to send JavaScript scripts to Adobe Illustrator and view the results, using AppleScript on MacOS.1-
- AlicenseAqualityDmaintenanceEnables AI assistants to control Adobe Illustrator on Windows, including creating, opening, saving, and exporting documents, drawing shapes, adding text, and running arbitrary ExtendScript.102MIT