Skip to main content
Glama
illustrator-bridge

illustrator-bridge

by groundfic

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

工具

工具

用途

會改文件?

connection_status

檢查 Illustrator 有沒有開、通道通不通

否

get_document_info

文件狀態:存檔路徑、未存修改、色彩模式、尺規單位、工作區域;圖層、色票、特別色、連結圖、字型、文字的摘要或完整清單

否

get_artboard_items

某個工作區域上的物件:類型、名稱、圖層、鎖定/隱藏、以工作區域左上角為原點的 mm 座標

否

take_snapshot

把工作區域匯出成圖片直接給 Claude 看,可裁切局部

否(見下)

check_document

一鍵印前檢查:色彩、文字、連結圖、出血、細線、疊印、雜物,回問題清單

否

list_scripts

列出登錄的現成 .jsx:用途、能否無介面執行、參數、驗證狀態

否

run_script

執行現成的 .jsx(登錄名稱或路徑),有介面的拒絕執行

看指令碼(會改的先備份)

create_artboards

主力。依規格批次建立,網格排列、自動命名

是(附加時先備份)

rename_artboards

依索引改名

是(先備份)

card_scan

解析卡片欄位,做成 CSV 範本

否

card_build

照表格批次複製卡片

是(先備份)

execute_jsx

逃生門:跑任意 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),依嚴重度排序。

檢查 only

類別(level)

color

rgbObjects CMYK 文件裡的 RGB 填色/筆畫(error)、rgbDocument RGB 文件(warn)、spots 特別色與用量(info)、unusedSpots(info)

links

missingLinks 遺失(error)、rgbImages CMYK 文件裡的 RGB 點陣圖(error)、distorted 非等比縮放(error)、lowRes 低於 minPPI(warn)、linkList 清單(info)

bleed

bleed 最上層物件離裁切線 0.1mm 內卻沒延伸出去(flushEdges)(warn)。1.2.1 起超出但不到 bleed mm 的(shortBleed)要 bleedStrict: true 才報;貼邊的點狀文字不報

stroke

thinStroke 細於 minStroke pt 的筆畫(warn)

overprint

whiteOverprint 白色(C0M0Y0K0、灰階 0、白色整體色)設了疊印(error)、overprint 其他疊印物件(info;特別色疊印列在這)

text

liveText 未轉外框的文字框,依工作區域計數,只列不判對錯(info)

clutter

strayPoints 孤立錨點、emptyText 空文字框(warn)、offArtboard 工作區域外、hiddenLocked 隱藏/鎖定/不列印圖層的物件(info)

  • 參數: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、判定依據、參數與預設值、作用對象、會不會改文件、驗證狀態。

名稱

指令碼

無介面

grid-guides

~/illustrator-scripts/grid-guides.jsx

✅ $.global.GRID_CONFIG(預設值取自對話框)

stamp-texture

~/illustrator-scripts/StampTexture.jsx

✅ $.global.STAMP_CONFIG(作用在選取)

glyph-parts

~/illustrator-scripts/stroke-split/GlyphParts.jsx

✅ GLYPH_PARTS_CONFIG(作用在選取)

ai-cover-finish/ai-cover-assemble

print-prepress/scripts/

✅ 照 run_adobe.sh 組 PARAMS+CONFIG+lib.jsx,需要 print-prepress 的 config.json

card-table

~/illustrator-scripts/CardTable.jsx

❌ 只有 ScriptUI

create-expanded-artboards

~/Documents/Illustrator-Scripts/CreateExpandedArtboards.jsx

✅ $.global.EXPAND_AB_CONFIG(1.2.1;作用在選取,unit 必填)

  • 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(沒給就是上面的預設單位)。

  • 可用單位:mm cm pt px in q(級/齒,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 的測試(都在自己新建的暫存文件上做,跑完關掉、作用中文件切回原本那份):

測試

內容

tests/dialog-guard.js

userInteractionLevel 設定與還原、alert 擋下

tests/backup.js

備份、去重、backup:false、未存檔文件

tests/snapshot.js

截圖尺寸、裁切、PNG、saved 前後一致、耗時

tests/docinfo.js

圖層/色票/特別色/連結(含遺失)/字型/文字、大文件耗時

tests/artboard-items.js

幾何比對、座標換算、鎖定/隱藏、群組展開、剪裁群組

tests/names-units.js

全形字元名稱、px 間距(走 MCP 通道)

tests/create-units.js

沒給 unit 時的預設單位:既有/新建 × CMYK/RGB × 有沒有給 unit,含間距、出血、回傳的 unitUsed/unitSource

tests/check.js

印前檢查:做壞的文件逐項抓、乾淨文件零誤報、RGB 文件、參數、3000 物件耗時

tests/scripts.js

run_script:中文編碼(對照 $.evalFile)、範圍隔離、拒絕、grid-guides/stamp-texture/glyph-parts/ai-cover-finish 實跑

tests/mcp-tools.js

新工具走 MCP 通道的整合測試

tests/card.js

卡片掃描與生成

需要「已存檔的文件」的測試(與測試圖檔、測試用 .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…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      A
      quality
      C
      maintenance
      An MCP server that lets AI assistants like Claude control Adobe Illustrator through natural language by executing ExtendScript code and providing document state inspection.
      12
      7
      MIT
    • A
      license
      A
      quality
      D
      maintenance
      Enables AI assistants to control Adobe Illustrator on Windows, including creating, opening, saving, and exporting documents, drawing shapes, adding text, and running arbitrary ExtendScript.
      10
      2
      MIT