Related Pages

Related topics: Getting Started, System Architecture

Project Overview

Introduction

illustrator-mcp-server is a Model Context Protocol (MCP) server that enables Claude, an AI assistant, to control Adobe Illustrator programmatically through natural language commands. This open-source project bridges the gap between AI capabilities and professional design workflows, allowing designers and developers to automate repetitive tasks, perform batch operations, and generate complex artwork through conversational interfaces.

Source: README.md

Purpose and Scope

The primary purpose of illustrator-mcp-server is to provide a comprehensive automation layer for Adobe Illustrator, making it accessible to users who may not have scripting experience while offering power users a flexible scripting alternative. The project serves multiple use cases:

• Design Automation: Automate repetitive design tasks such as batch exports, color replacements, and object alignment
• Pre-press Validation: Perform comprehensive print-readiness checks including PDF/X compliance verification
• Document Generation: Create new documents with specific dimensions, color modes, and structures programmatically
• Design Assistance: Enable AI-driven design workflows where Claude can generate artwork, layout suggestions, and style guides

Source: README.md

Architecture Overview

The system follows a client-server architecture built on the Model Context Protocol:

graph TD
    subgraph "Client Layer"
        Claude[Claude AI Assistant]
        ClaudeCode[Claude Code CLI]
        ClaudeDesktop[Claude Desktop App]
    end
    
    subgraph "MCP Protocol Layer"
        MCPServer[MCP Server<br/>illustrator-mcp-server]
    end
    
    subgraph "Adobe Illustrator"
        AI[Adobe Illustrator]
        AS[AppleScript / COM]
    end
    
    Claude -->|MCP Protocol| MCPServer
    MCPServer -->|Node.js 20+| AS
    AS -->|Automation API| AI
    
    ClaudeCode -.->|mcp add| MCPServer
    ClaudeDesktop -.->|npx / .mcpb| MCPServer

Technology Stack

Source: README.md

Core Feature Summary

Tool Categories

The server provides over 60 tools organized into functional categories:

Source: README.md

Automatic Coordinate System Detection

One of the distinguishing features is intelligent coordinate system detection based on document color mode:

graph LR
    A[Document Opens] --> B{Color Mode?}
    B -->|CMYK| C[document<br/>coordinate system]
    B -->|RGB| D[artboard-web<br/>coordinate system]
    
    C --> E[Origin: Bottom-left<br/>Y-axis: Up]
    D --> F[Origin: Top-left<br/>Y-axis: Down]
    
    E -.->|Print designers<br/>expect| C
    F -.->|Web developers<br/>expect| D

Source: README.md

Print Production Tools

The project includes specialized tools for print production workflows:

• preflight_check: Validates RGB color mixing, broken links, low resolution images, white overprint, transparency conflicts, and PDF/X compliance
• check_text_consistency: Detects placeholders, notation variations (including Japanese double-line/Western single-line), and provides full text listing for LLM analysis
• export_pdf: Generates print-ready PDFs with crop marks, bleed settings, selective downsampling, and output intent

Source: README.md

Installation Methods

Claude Code

claude mcp add illustrator-mcp -- npx illustrator-mcp-server

Claude Desktop

#### Method 1: Direct Installation

1. Download illustrator-mcp-server.mcpb from GitHub Releases
2. Open Claude Desktop → Settings → Extensions
3. Drag and drop the .mcpb file
4. Click Install

#### Method 2: Manual Configuration

{
  "mcpServers": {
    "illustrator": {
      "command": "npx",
      "args": ["illustrator-mcp-server"]
    }
  }
}

Note: If Node.js is installed via a version manager (nvm, mise, fnm), use the full path: "command": "/full/path/to/npx"

Source: README.md

Example Workflows

Video Test Pattern Generation

A complete SMPTE color bar test pattern created entirely through natural language prompts:

Prompt:

Create a 1920x1080 video test pattern

Result:

• SMPTE color bars with PLUGE patterns
• Title safe and action safe zones
• Center crosshair markers
• Resolution and format labels

Tools Used: create_document, manage_layers ×4, create_rectangle ×2, create_gradient ×2, create_path ×11, create_ellipse ×14, create_line ×4, create_text_frame ×2, modify_object, set_z_order, export

Source: README.md

PDF/X-1a Compliance Check

sequenceDiagram
    participant User
    participant Claude
    participant MCP_Server
    participant Illustrator
    
    User->>Claude: Check if document is PDF/X-1a compliant
    Claude->>MCP_Server: preflight_check(target_pdf_profile: "x1a")
    MCP_Server->>Illustrator: Run preflight analysis
    Illustrator-->>MCP_Server: Return compliance results
    MCP_Server-->>Claude: Display errors and warnings
    Claude-->>User: Structured report with issues
    
    Note over MCP_Server: Flags: transparency,<br/>RGB colors in CMYK,<br/>non-outlined fonts

Source: README.md

Platform Support

Source: README.md

Known Limitations

Source: README.md

Testing Infrastructure

Test Categories

The E2E smoke test performs:

• Creates fresh documents (RGB + CMYK)
• Places test objects
• Executes 182 test cases across 10 phases
• Covers all registered tools and coordinate system auto-detection
• Automatic cleanup after completion

Source: README.md

Disclaimer

This tool automates many Illustrator operations, but AI can make mistakes. Extracted data, preflight results, and document modifications should always be reviewed by a human. The tool should not be relied upon as the sole quality check, especially for print submissions and client deliverables.

Important: The authors are not responsible for any damages or losses arising from the use of this software or its outputs.

Source: README.md

License

This project is released under the MIT License.

Related Pages

Related topics: Project Overview, Development Guide

Getting Started

Overview

This guide provides comprehensive instructions for setting up and running the illustrator-mcp-server, a Model Context Protocol (MCP) server that enables AI assistants like Claude to control Adobe Illustrator through natural language commands. The server acts as a bridge between Claude and Illustrator's scripting capabilities, allowing users to create, modify, and export artwork programmatically. Source: README.md

System Requirements

Before installation, ensure your system meets the following requirements:

Source: README.md

Installation Methods

The illustrator-mcp-server supports multiple installation approaches depending on your workflow and preferences.

Method 1: Claude Code (Recommended)

The simplest installation method for Claude Code users requires only the npx command execution. Source: README.md

claude mcp add illustrator-mcp -- npx illustrator-mcp-server

This command registers the illustrator-mcp-server as an MCP tool that Claude Code can access. The server will be downloaded and executed on-demand via npx.

Method 2: Claude Desktop with .mcpb File

For Claude Desktop users, download the pre-built .mcpb file from GitHub Releases. Source: README.md

Steps:

1. Download illustrator-mcp-server.mcpb from GitHub Releases
2. Open Claude Desktop → Settings → Extensions
3. Drag and drop the .mcpb file into the Extensions panel
4. Click the Install button

[!NOTE]

The .mcpb extension does not auto-update. To update, download the new version and reinstall. If you prefer automatic updates, use the npx method instead. Source: README.md

Method 3: Claude Desktop Manual Configuration

For users who prefer automatic updates or need custom configuration, manually edit the Claude Desktop configuration file. Source: README.md

#### Step 1: Open the Configuration File

From the Claude Desktop menu bar:

• Claude → Settings... → Developer (in the left sidebar) → Click the Edit Config button

#### Step 2: Add Server Configuration

{
  "mcpServers": {
    "illustrator": {
      "command": "npx",
      "args": ["illustrator-mcp-server"]
    }
  }
}

[!NOTE]

If you installed Node.js via a version manager (nvm, mise, fnm, etc.), Claude Desktop may not find npx. In that case, use the full path. Run which npx in your terminal to find the path. Source: README.md

"command": "/full/path/to/npx"

#### Step 3: Save and Restart

1. Save the file and close the text editor
2. Fully quit Claude Desktop (⌘Q / Ctrl+Q) and reopen

Building from Source

For development, testing, or customization purposes, build the server from the source code. Source: README.pt-BR.md

Prerequisites

• Git
• Node.js 20+
• npm

Build Steps

git clone https://github.com/ie3jp/illustrator-mcp-server.git
cd illustrator-mcp-server
npm install
npm run build

After building, register the local server:

claude mcp add illustrator-mcp -- node /path/to/illustrator-mcp-server/dist/index.js

Verification

After installation, verify that the server is properly configured by running the MCP inspector. Source: README.pt-BR.md

npx @modelcontextprotocol/inspector npx illustrator-mcp-server

The inspector provides an interactive interface to test MCP tool calls and confirm connectivity.

Testing

The project includes comprehensive test suites to validate functionality across different scenarios.

Unit Tests

Run the unit test suite to verify core functionality:

npm test

End-to-End Smoke Tests

The E2E smoke test creates new documents (RGB + CMYK), inserts test objects, executes 182 test cases across 10 phases covering all registered tools and automatic coordinate system detection, then performs automatic cleanup. Source: README.pt-BR.md

npx tsx test/e2e/smoke-test.ts

[!NOTE]

E2E tests require Illustrator to be running. The smoke test will connect to the running instance and perform operations on temporary documents.

Initial Configuration

macOS Automation Permissions

On first run, macOS requires explicit permission for automation access. Navigate to:

System Settings → Privacy & Security → Automation

Locate Claude Desktop in the list and enable access for the automation permissions requested. Source: README.md

Multiple Illustrator Versions

If you have multiple versions of Illustrator installed, you can specify which version to use during conversation. Simply say "Use Illustrator 2024" and the set_illustrator_version tool will target that version. Source: README.md

[!NOTE]

If Illustrator is already running, the server connects to the running instance automatically.

Windows PowerShell Configuration

Windows uses PowerShell COM automation for Illustrator control. This functionality has not been tested on real hardware yet. Source: README.es.md

Workflow Modes

The server supports different workflow modes that affect coordinate system handling. Source: README.md

• CMYK documents use Illustrator's native coordinate system, matching what print designers expect
• RGB documents use a web-based coordinate system with origin at the top-left

Use the set_workflow tool to override the auto-detected coordinate system when needed.

Quick Start Workflow

The following diagram illustrates the typical workflow when using the illustrator-mcp-server:

graph TD
    A[User Input] --> B{Server Running?}
    B -->|No| C[Start Illustrator]
    B -->|Yes| D[Connect to Illustrator]
    C --> D
    D --> E[Send MCP Request]
    E --> F[Process Tool Call]
    F --> G{Modify or Read?}
    G -->|Modify| H[Execute Illustrator Action]
    G -->|Read| I[Query Illustrator State]
    H --> J[Return Result]
    I --> J
    J --> K[User Receives Response]
    
    L[Export Tools] --> M[SVG / PNG / PDF]
    H --> L

First-Time Usage Example

A typical first session might involve creating a new document and adding basic elements. Source: README.md

# Create a new 1920x1080 document
You: Create a new Full HD document

Claude: → create_document (width: 1920, height: 1080, color_mode: "rgb")
         ✅ Created new document "Untitled-1"

# Add a rectangle
You: Add a blue rectangle in the center

Claude: → create_rectangle (x: 760, y: 390, width: 400, height: 300, fill: "#007AFF")
         ✅ Rectangle created

# Export the result
You: Export as PNG

Claude: → export (format: "png", artboard: 0)
         ✅ Exported to /output/Untitled-1.png

Known Limitations

Before starting your project, be aware of the following limitations: Source: README.es.md

Troubleshooting

npx Not Found

If Claude Desktop cannot find npx, install Node.js via the official installer from nodejs.org instead of using version managers like nvm, mise, or fnm. Alternatively, use the full path to npx. Source: README.md

Illustrator Not Launching

Modify and export tools will bring Illustrator to the foreground during execution. If Illustrator fails to launch, ensure it is properly installed and you have the necessary permissions. Source: README.md

Permission Denied on macOS

Grant automation permissions in System Settings → Privacy & Security → Automation and ensure Claude Desktop is listed with appropriate access.

Next Steps

After successful installation, explore the available tools:

• Read Tools (21): get_document_info, get_artboards, get_layers, get_document_structure, list_text_frames, get_colors, get_path_items, get_images, and more
• Modify Tools (38): create_rectangle, create_ellipse, create_text_frame, create_path, modify_object, align_objects, manage_layers, and more
• Export Tools (2): export, export_pdf
• Utility Tools (3): preflight_check, check_text_consistency, set_workflow

Source: README.md

[!CAUTION]

AI can make mistakes. Do not over-rely on the output — always have a human perform the final check on submission data. The user is responsible for the results. Source: README.md

Related Pages

Related topics: Execution Flow, Project Overview

System Architecture

Overview

The illustrator-mcp-server is a Model Context Protocol (MCP) server that enables AI assistants like Claude to interact with Adobe Illustrator through a standardized interface. The server acts as a bridge between natural language instructions from AI systems and the Adobe Illustrator scripting API, providing automation capabilities for document manipulation, design tasks, and pre-press operations.

The architecture follows a tool-based pattern where each Illustrator operation is exposed as an individual MCP tool. The server handles connection management, coordinate system transformations, and result serialization to provide a seamless experience for AI-driven design workflows.

High-Level Architecture

graph TB
    subgraph "Client Layer"
        AI[AI Assistant<br/>Claude, etc.]
        MCP[MCP Client]
    end
    
    subgraph "Server Layer"
        Server[MCP Server]
        Registry[Tool Registry]
        Executor[Tool Executor]
    end
    
    subgraph "Adobe Illustrator"
        API[ExtendScript API<br/>JavaScript Bridge]
        App[Illustrator Application]
    end
    
    AI --> MCP
    MCP --> Server
    Server --> Registry
    Server --> Executor
    Executor --> API
    API --> App
    
    style AI fill:#e1f5fe
    style App fill:#fff3e0

Core Components

Tool Registry

The tool registry maintains a catalog of all available MCP tools organized into functional categories. Each tool is registered with metadata including its name, description, input schema, and handler function.

Tool Categories:

Source: README.md

Coordinate System Management

The server implements automatic coordinate system detection based on document color mode:

CMYK documents use Illustrator's native coordinate system matching print designer expectations, while RGB documents use a web-friendly coordinate system with origin at the top-left of the artboard. The set_workflow tool allows manual override of the auto-detected system.

Source: README.md

Tool Execution Flow

sequenceDiagram
    participant AI as AI Assistant
    participant MCP as MCP Server
    participant Registry as Tool Registry
    participant Exec as Executor
    participant App as Illustrator API
    
    AI->>MCP: Tool Request
    MCP->>Registry: Lookup Tool Definition
    Registry-->>MCP: Tool Schema
    MCP->>Exec: Execute Tool Call
    Exec->>App: Invoke Illustrator Script
    App-->>Exec: Script Result
    Exec-->>MCP: Serialized Response
    MCP-->>AI: JSON-RPC Response

System Architecture Layers

Layer 1: Client Interface

The MCP protocol defines how AI assistants communicate with the server. Clients connect using the MCP handshake protocol and receive the tool manifest during initialization.

Connection Methods:

// Claude Desktop Configuration
{
  "mcpServers": {
    "illustrator": {
      "command": "npx",
      "args": ["illustrator-mcp-server"]
    }
  }
}

Source: README.md

Layer 2: Server Implementation

The server layer handles:

• MCP protocol message parsing and routing
• Tool registration and discovery
• Request validation and error handling
• Response serialization

The server automatically manages Illustrator application connections, including support for multiple installed versions. The set_illustrator_version tool allows targeting specific Illustrator versions during a session.

Layer 3: Illustrator Bridge

The bridge layer communicates with Adobe Illustrator through the ExtendScript/JavaScript API. This layer handles:

• Application state management (launch, connect, disconnect)
• Script execution and result parsing
• Coordinate transformation between coordinate systems
• Error translation from Illustrator errors to MCP-friendly messages

Source: README.md

Tool Organization

Read Tools (21 tools)

These tools extract information from the active Illustrator document:

Source: README.md

Modify Tools (38 tools)

These tools create and modify document elements:

Source: README.md

Export Tools (2 tools)

Source: README.md

Utility Tools (3 tools)

Source: README.md

Data Flow Architecture

graph LR
    subgraph "Input Processing"
        Req[Tool Request] --> Parse[Parse & Validate]
        Parse --> Transform[Coordinate Transform]
    end
    
    subgraph "Illustrator Processing"
        Transform --> Script[Generate Script]
        Script --> Execute[Execute in Illustrator]
        Execute --> Result[Capture Result]
    end
    
    subgraph "Output Processing"
        Result --> Serialize[Serialize Response]
        Serialize --> Out[JSON-RPC Response]
    end
    
    style Input Processing fill:#e8f5e9
    style Illustrator Processing fill:#fff8e1
    style Output Processing fill:#e3f2fd

Multiple Illustrator Version Support

The architecture supports concurrent installation of multiple Illustrator versions. The server can detect available versions and route requests to the appropriate application instance.

graph TD
    Start[Start Session] --> Check{Running Instance?}
    
    Check -->|Yes| Connect[Connect to Running]
    Check -->|No| Detect[Detect Versions]
    
    Detect --> Select[Select Version]
    Select --> Launch[Launch Illustrator]
    
    Connect --> Ready
    Launch --> Ready
    
    Ready[Ready for Commands]
    
    User[User: "Use Illustrator 2024"] --> Override
    Override[Call set_illustrator_version]
    Override --> Ready

Source: README.md

Workflow Modes

The server operates in two primary workflow modes that affect coordinate handling:

Web/Print Workflow

The server automatically detects the appropriate mode based on the document's color mode. Manual override is available via the set_workflow tool when AI needs consistent coordinate behavior.

Source: README.md

Error Handling Architecture

graph TD
    Script[Script Execution] --> Success{Success?}
    
    Success -->|Yes| Return[Return Result]
    Success -->|No| Identify[Identify Error Type]
    
    Identify -->|API Error| IllustratorError[Illustrator Error]
    Identify -->|Connection Error| ConnectionError[Connection Lost]
    Identify -->|Validation Error| ValidationError[Invalid Parameters]
    
    IllustratorError --> MCPError[Format as MCP Error]
    ConnectionError --> Reconnect[Attempt Reconnect]
    ValidationError --> MCPError
    
    Reconnect --> Success
    MCPError --> Response[Error Response]
    Return --> Response
    
    style Response fill:#ffcdd2

Build and Deployment

Project Structure

illustrator-mcp-server/
├── dist/              # Compiled JavaScript output
├── src/               # TypeScript source files
│   ├── server.ts      # MCP server implementation
│   ├── index.ts       # Entry point
│   └── tools/         # Tool implementations
├── test/              # Test files
│   └── e2e/           # End-to-end smoke tests
└── package.json       # Dependencies and scripts

Build Commands

npm install        # Install dependencies
npm run build      # Compile TypeScript to JavaScript
npm test           # Run unit tests

Source: README.md

Verification

npx @modelcontextprotocol/inspector npx illustrator-mcp-server

The MCP inspector tool validates that the server correctly implements the protocol and exposes all registered tools.

Limitations and Architecture Constraints

Source: README.pt-BR.md

Security Considerations

The architecture includes several safety mechanisms:

1. Manual Verification Required: All extracted data, preflight results, and document modifications require human review before final submission
2. Foreground Execution: Modify and export tools bring Illustrator to the foreground during execution
3. Automation Permissions: macOS requires explicit automation access in System Settings → Privacy & Security → Automation

Source: README.md

Related Pages

Related topics: System Architecture, Coordinate Systems

Execution Flow

Overview

The execution flow is the core mechanism by which the MCP server communicates with Adobe Illustrator to perform design operations. Since Illustrator does not natively support the MCP (Model Context Protocol) or direct Node.js integration, the server acts as an intermediary that translates tool requests into ExtendScript (JSX) commands that Illustrator can execute. This architectural pattern enables Claude and other MCP-compatible AI assistants to control Adobe Illustrator programmatically.

The execution flow handles tool parameter serialization, cross-platform script generation (AppleScript for macOS, PowerShell for Windows), and result retrieval through a file-based transport mechanism. Source: README.md

Architecture Overview

flowchart LR
    Claude <-->|MCP Protocol| Server["MCP Server\n(TypeScript/Node.js)"]

    Server -.->|generate| Runner["run-{uuid}.scpt / .ps1"]
    Server -.->|generate| JSX["script-{uuid}.jsx\n(BOM UTF-8)"]
    Server -.->|write| PF["params-{uuid}.json"]

    Runner -->|execFile| osascript
    Runner -->|execFile| PS["powershell.exe"]

    osascript -->|do javascript| AI["Adobe Illustrator\n(ExtendScript/JSX)"]
    PS -->|DoJavaScript| AI

    JSX -.->|execute| AI
    PF -.->|read| AI
    AI -.->|write| RF["result-{uuid}.json"]
    RF -.->|read| Server

The system comprises four primary components that communicate through the file system:

Source: README.md

Execution Pipeline Stages

Stage 1: Tool Registration and Discovery

The MCP server registers all available tools during initialization. Each tool defines a name, input schema, and handler function. Tools are organized into categories (read, modify, export, utility) and are exposed to Claude through the MCP protocol. Source: src/tools/tool-executor.ts

Stage 2: Request Handling

When a tool request arrives, the server performs the following validation and preparation steps:

1. Schema validation — Verify all required parameters are present
2. Coordinate system detection — Determine whether the document uses document (CMYK/print) or artboard-web (RGB/web) coordinates
3. UUID generation — Create a unique identifier for tracking this execution cycle
4. Script selection — Load the appropriate JSX template for the requested operation

Source: src/tools/tool-executor.ts

Stage 3: Parameter Serialization

Parameters are serialized into a JSON file using the file transport mechanism. This file-based approach is necessary because ExtendScript and the Illustrator DOM cannot directly receive complex JavaScript objects from the Node.js process. Source: src/executor/file-transport.ts

The parameter file follows the naming convention params-{uuid}.json and contains typed parameters that the JSX script will read during execution.

Stage 4: Script Generation

The server generates two scripts for each execution:

JSX Script (script-{uuid}.jsx)

• Written in BOM-encoded UTF-8 (required for Illustrator compatibility with non-ASCII characters)
• Contains the ExtendScript code that manipulates the Illustrator document
• References the parameter file path
• Writes results to result-{uuid}.json

Runner Script

• macOS: AppleScript (.scpt) that executes osascript with the JSX path
• Windows: PowerShell (.ps1) that executes Illustrator via COM automation
• Handles platform-specific execution context and error propagation

Source: src/executor/jsx-runner.ts

Stage 5: Cross-Platform Execution

flowchart TD
    subgraph macOS
        A[Node.js Server] --> B[Generate .scpt]
        B --> C[osascript]
        C --> D[do javascript]
        D --> E[Adobe Illustrator]
    end

    subgraph Windows
        F[Node.js Server] --> G[Generate .ps1]
        G --> H[powershell.exe]
        H --> I[DoJavaScript]
        I --> J[Adobe Illustrator]
    end

The runner script invokes the appropriate shell command based on the operating system:

macOS Execution Path

osascript -l JavaScript "/path/to/script-{uuid}.jsx"

Windows Execution Path

$ai = New-Object -ComObject Illustrator.Application
$ai.DoJavaScript("/path/to/script-{uuid}.jsx")

Source: src/executor/jsx-runner.ts

Stage 6: JSX Execution

The ExtendScript environment within Illustrator reads the parameter file and executes the DOM operations. The script has access to:

• The active document and its properties
• The parameter values serialized by the server
• Helper utilities from src/jsx/helpers/common.jsx

Common helper functions include UUID management, artboard coordinate conversion, and result file writing. Source: src/jsx/helpers/common.jsx

Stage 7: Result Collection

After execution completes, the JSX script writes a result file (result-{uuid}.json) containing:

Source: src/executor/file-transport.ts

Stage 8: Response Assembly

The MCP server reads the result file, parses the JSON payload, and constructs an MCP-formatted response that is sent back to Claude. If the operation failed, the response includes error details for debugging.

Coordinate System Handling

The server automatically detects and handles coordinate system differences between document types:

Conversion utilities in the JSX helpers transform coordinates between systems as needed. Source: src/jsx/helpers/common.jsx

Error Handling

The execution flow includes multiple error handling layers:

1. Parameter validation — Invalid inputs are rejected before script generation
2. Script compilation errors — Malformed JSX is caught and reported
3. Runtime errors — Illustrator DOM errors are captured in the result file
4. File system errors — Missing or unwritable paths are detected

Example error response structure:

{
  "error": true,
  "message": "Symbol not found: MySymbol",
  "line": 42
}

Source: src/tools/modify/place-symbol.ts

Export-Specific Execution

Export operations follow the standard flow but include additional file verification steps:

flowchart TD
    Start[export tool called] --> Validate[Validate format & artboard]
    Validate --> Generate[Generate export script]
    Generate --> Execute[Run JSX via runner]
    Execute --> Check{Output file exists?}
    Check -->|Yes| DpiCalc[Calculate effective DPI]
    Check -->|No| Error[Write error result]
    DpiCalc --> Write[Write success result]
    Write --> Done[Return to Claude]
    Error --> Done

The export handler verifies the output file was created and includes effective DPI calculations in the result. Source: src/tools/export/export.ts

Build and Packaging

The server is compiled using a custom build script that:

1. Compiles TypeScript to JavaScript via tsc
2. Copies JSX files to the distribution directory
3. Bundles the server into a CommonJS module for Node.js compatibility

npm run build

Source: package.json

Testing the Execution Flow

End-to-end smoke tests validate the complete flow by:

1. Creating fresh RGB and CMYK documents
2. Placing test objects via all registered tools
3. Running 182 test cases across 10 phases
4. Verifying coordinate system auto-detection
5. Cleaning up automatically

npx tsx test/e2e/smoke-test.ts

Source: README.md

Summary

The execution flow transforms high-level tool requests from Claude into Illustrator DOM operations through a file-based transport mechanism. This architecture enables:

• Cross-platform support (macOS and Windows)
• Type-safe parameter passing via JSON
• BOM UTF-8 encoding for international character support
• Automatic coordinate system handling
• Comprehensive error reporting
• Asynchronous execution with UUID tracking

The separation between the MCP server, runner scripts, and JSX execution ensures that Illustrator remains isolated from the Node.js process, preventing compatibility issues between the different scripting environments.

Related Pages

Related topics: Modify Tools, Export Tools

Read Tools

Read Tools in illustrator-mcp-server provide comprehensive read-only access to Adobe Illustrator documents. These 21 tools enable AI assistants like Claude to inspect, analyze, and extract information from open documents without modifying them. Read Tools serve as the foundation for document analysis, design auditing, preflight checks, and AI-driven content understanding.

Overview

Read Tools are categorized into four functional areas:

The tool architecture follows a consistent pattern where each tool returns structured JSON data suitable for AI consumption and analysis. All Read Tools operate on the currently active Illustrator document and do not modify document state.

Architecture

graph TD
    A[AI Assistant] -->|MCP Protocol| B[illustrator-mcp-server]
    B -->|COM/AppleScript| C[Adobe Illustrator]
    C -->|Document Data| B
    B -->|Structured JSON| A
    
    B --> D[Read Tools]
    B --> E[Modify Tools]
    B --> F[Export Tools]
    B --> G[Utility Tools]
    
    D --> D1[Document Tools]
    D --> D2[Text Tools]
    D --> D3[Visual Tools]
    D --> D4[Compliance Tools]

Tool Registration Pattern

Read Tools are registered as MCP (Model Context Protocol) handlers in the server initialization. Each tool follows this standard structure:

Tool Name → Handler Function → Illustrator Script → JSON Response

Source: src/tools/read/get-document-info.ts

Document Analysis Tools

get_document_info

Retrieves comprehensive metadata about the active Illustrator document.

Parameters:

Returns:

Source: src/tools/read/get-document-info.ts

get_artboards

Returns information about all artboards in the document.

Returns:

Source: src/tools/read/get-document-structure.ts

get_document_structure

Provides a complete hierarchical tree of the document contents.

Returns: Nested tree structure:

Document
└── Layers
    ├── Groups
    │   └── Objects
    ├── Text Frames
    ├── Paths
    ├── Images
    └── Symbols

Object Properties Returned:

Source: src/tools/read/get-document-structure.ts

convert_coordinate

Converts coordinates between the document coordinate system and artboard coordinate system.

Parameters:

Coordinate System Reference:

Source: src/tools/read/get-document-info.ts

Text Analysis Tools

list_text_frames

Enumerates all text frames in the document with key attributes.

Returns:

Source: src/tools/read/list-text-frames.ts

get_text_frame_detail

Returns comprehensive attributes for a specific text frame.

Parameters:

Returns:

Source: src/tools/read/get-text-frame-detail.ts

Color Analysis Tools

get_colors

Extracts all color definitions used in the document.

Parameters:

Returns:

Diagnostics (when enabled):

Source: src/tools/read/get-colors.ts

extract_design_tokens

Exports document colors and typography as design system tokens.

Parameters:

Output Formats:

Source: src/tools/read/extract-design-tokens.ts

Image Analysis Tools

get_images

Returns information about all embedded and linked images.

Parameters:

Returns:

Print Information (when enabled):

Source: src/tools/read/get-images.ts

Visual Element Tools

get_path_items

Returns path and shape data for vector objects.

Returns:

Path Types:

get_groups

Returns group hierarchy and structure.

Returns:

get_symbols

Returns symbol definitions and all instances in use.

Returns:

get_effects

Returns effects and appearance settings.

Returns:

get_guidelines

Returns guide line information.

Returns:

Compliance & Accessibility Tools

check_contrast

Performs WCAG color contrast ratio analysis.

Parameters:

Returns:

WCAG Thresholds:

Source: src/tools/read/check-contrast.ts

find_objects

Searches document objects by various criteria.

Parameters:

get_overprint_info

Returns overprint settings and rich black detection.

Returns:

get_separation_info

Returns color separation information for print production.

Returns:

get_selection

Returns details of currently selected objects.

Returns:

Workflow Integration

Read Tools integrate with Modify and Export Tools in complex workflows:

graph LR
    A[Read Tools] -->|Inspect| B[Document Analysis]
    A -->|Validate| C[Preflight Check]
    A -->|Extract| D[Design Tokens]
    
    B --> E[Modify Tools]
    C --> F[Utility Tools]
    D --> G[Export Tools]
    
    E --> H[Document Updates]
    F --> I[Compliance Report]
    G --> J[Asset Export]

Example Workflow: Export with Text Outlining

get_artboards → Identify target artboards
convert_to_outlines → Convert fonts to paths
export → Export as SVG/PNG

Example Workflow: Print Preflight

get_document_info → Check color mode
get_colors → Validate color definitions
get_images → Verify image resolution
get_overprint_info → Check overprint settings
preflight_check → Comprehensive report

Common Usage Patterns

Document Analysis Pattern

// Get full document context
const docInfo = await get_document_info();
const structure = await get_document_structure();
const colors = await get_colors({ include_diagnostics: true });

Text Audit Pattern

// Comprehensive text analysis
const textFrames = await list_text_frames();
const details = await Promise.all(
    textFrames.map(tf => get_text_frame_detail({ uuid: tf.uuid }))
);

Design System Extraction Pattern

// Export as CSS custom properties
const tokens = await extract_design_tokens({ 
    format: "css",
    scope: "all" 
});

Limitations

See Also

• Modify Tools - Tools for editing document content
• Export Tools - Tools for exporting documents
• Utility Tools - Pre-flight and workflow utilities
• Preflight Workflow - Complete print compliance workflow

Related Pages

Related topics: Read Tools, Export Tools

Modify Tools

Overview

The Modify Tools are a collection of 38 tools within the illustrator-mcp-server that enable AI assistants (specifically Claude) to create, modify, and manipulate objects in Adobe Illustrator documents through natural language commands. These tools form the core of the server's ability to perform design operations by bridging natural language instructions with the Adobe Illustrator scripting API.

The Modify Tools handle everything from basic shape creation (rectangles, ellipses, lines) to complex operations like object grouping, layer management, and document saving. They are designed to work seamlessly with the Read Tools and Export Tools to provide a complete workflow for automated design tasks.

Architecture

Tool Categories

The Modify Tools are organized into several functional categories:

graph TD
    A[Modify Tools] --> B[Shape Creation]
    A --> C[Text Creation]
    A --> D[Object Manipulation]
    A --> E[Layer Management]
    A --> F[Document Operations]
    A --> G[Color Management]
    
    B --> B1[create_rectangle]
    B --> B2[create_ellipse]
    B --> B3[create_line]
    B --> B4[create_path]
    
    C --> C1[create_text_frame]
    
    D --> D1[modify_object]
    D --> D2[group_objects]
    D --> D3[ungroup_objects]
    D --> D4[duplicate_objects]
    D --> D5[align_objects]
    D --> D6[set_z_order]
    D --> D7[move_to_layer]
    
    E --> E1[manage_layers]
    
    F --> F1[create_document]
    F --> F2[open_document]
    F --> F3[save_document]
    F --> F4[close_document]
    
    G --> G1[manage_swatches]
    G --> G2[replace_color]
    G --> G3[assign_color_profile]

Relationship with Coordinate Systems

All Modify Tools automatically adapt to the document's coordinate system, which is auto-detected based on the document type:

Source: README.md - Coordinate System

Related Pages

Related topics: Read Tools, Modify Tools

Export Tools

The Export Tools module provides capabilities for exporting Adobe Illustrator documents and artwork to various file formats suitable for web, print, and digital distribution. This module consists of two primary tools: export for raster and vector formats (SVG, PNG, JPG), and export_pdf for print-ready PDF production with professional prepress features.

Overview

Export Tools are classified under Phase 3 of the illustrator-mcp-server architecture, focusing on export operations and print-oriented reading capabilities. These tools enable Claude to transform Illustrator documents into standardized output formats while maintaining design integrity and supporting industry-standard print production workflows.

Source: src/tools/registry.ts:9-10

Architecture

Component Interaction

flowchart TD
    subgraph Server["illustrator-mcp-server"]
        ExportTool["export tool"]
        ExportPdfTool["export_pdf tool"]
    end
    
    subgraph Illustrator["Adobe Illustrator"]
        JSX["JSX Script\n(ExtendScript)"]
        Document["Active Document"]
        Artboards["Artboards Collection"]
    end
    
    ExportTool -->|generates| ExportJSX["script-{uuid}.jsx"]
    ExportPdfTool -->|generates| PdfJSX["script-{uuid}.jsx"]
    
    ExportJSX -->|executes| Illustrator
    PdfJSX -->|executes| Illustrator
    
    Illustrator -->|writes| ResultFile["result-{uuid}.json"]
    ResultFile -->|reads| Server
    
    Document -->|exports to| SVG["SVG File"]
    Document -->|exports to| PNG["PNG File"]
    Document -->|exports to| PDF["PDF File"]

Export Workflow Sequence

sequenceDiagram
    participant Client as Claude/Client
    participant Server as MCP Server
    participant AI as Adobe Illustrator
    
    Client->>Server: Request export (format, options)
    Server->>Server: Generate UUID
    Server->>Server: Create params-{uuid}.json
    Server->>Server: Create script-{uuid}.jsx
    Server->>Server: Execute via osascript/PS
    
    rect rgb(200, 220, 240)
        Note over AI: Illustrator executes JSX script
        AI->>AI: Load parameters
        AI->>AI: Open/access document
        AI->>AI: Apply export settings
        AI->>AI: Write output file
        AI->>AI: Write result-{uuid}.json
    end
    
    Server->>Server: Read result-{uuid}.json
    Server->>Client: Return export result
    
    alt Verification Required
        Server->>Server: Check file existence
        alt File not created
            Server->>Client: Error with path details
        end
    end

Export Tool (`export`)

The export tool handles conversion of Illustrator content to web-friendly and raster formats. It supports exporting by artboard, selection, or specific object UUID.

Tool Registration

server.registerTool(
  'export',
  {
    title: 'Export',
    description: 'Export objects, groups, artboards...',
    inputSchema: {
      // Parameters defined in source
    }
  }
);

Source: src/tools/export/export.ts:55-60

Supported Formats

Export Options

Raster Export Details

For PNG and JPG exports, the effective DPI is calculated by multiplying the specified DPI by the scale factor:

{
  "success": true,
  "output_path": "/path/to/output.png",
  "format": "png",
  "dpi": 144,
  "scale": 2
}

Source: src/tools/export/export.ts:42-45

SVG Export Behavior

The SVG export includes special handling for artboard-named files:

1. When exporting an artboard with format svg and an artboard_index is specified
2. The output filename follows pattern: {baseName}_{artboardName}.svg
3. Artboard names have spaces replaced with hyphens

Example:

• Document: design.ai in /output/
• Artboard: hero section
• Output: /output/design_hero-section.svg

Source: src/tools/export/export.ts:18-28

Verification and Error Handling

The tool performs post-export verification:

var finalFile = new File(actualPath);
if (!finalFile.exists) {
  writeResultFile(RESULT_PATH, { 
    error: true, 
    message: "Export completed but output file was not created. The path may not be writable: " + outputPath 
  });
}

Source: src/tools/export/export.ts:46-48

Export PDF Tool (`export_pdf`)

The export_pdf tool generates print-ready PDF files with comprehensive prepress options including crop marks, bleed settings, and PDF preset support.

Tool Registration

server.registerTool(
  'export_pdf',
  {
    title: 'Export PDF',
    description: 'Export print-ready PDF. Note: Illustrator will be activated (brought to foreground) during execution.',
    inputSchema: {
      output_path: z.string().optional(),
      preset: z.string().optional(),
      options: z.object({...})
    }
  }
);

Source: src/tools/export/export-pdf.ts:54-68

PDF Export Parameters

Japanese Crop Marks

The PDF export includes specialized handling for Japanese crop marks. When marks_style is set to japanese, the system:

1. Generates Japanese crop marks using the Illustrator TrimMark command
2. Creates marks as document paths for reliable rendering
3. Removes marks after PDF export via undo operation
4. Includes a note in the result indicating this behavior

if (writeResult.japanese_marks_note) {
  result.japanese_marks_note = "Japanese crop marks were generated as document paths via TrimMark command for reliable rendering, then removed after export.";
}

Source: src/tools/export/export-pdf.ts:21-23

PDF Presets

Common PDF presets supported by Illustrator include:

PDF Export Result

Successful PDF export returns:

{
  "success": true,
  "output_path": "/path/to/document.pdf",
  "format": "pdf"
}

Error Handling

PDF export errors include line number information for debugging:

catch (e) {
  writeResultFile(RESULT_PATH, { 
    error: true, 
    message: "PDF export failed: " + e.message, 
    line: e.line 
  });
}

Source: src/tools/export/export-pdf.ts:30-32

Coordinate System Considerations

Export tools automatically handle coordinate system differences based on document color mode:

This affects how coordinates are interpreted during export, particularly for SVG output where coordinate transformation may be required.

Integration with Preflight

Export tools are commonly used in conjunction with the preflight check tool for print workflows:

flowchart LR
    Preflight["preflight_check"] --> |Validates| Doc["Document"]
    Doc --> |If compliant| ExportPDF["export_pdf"]
    ExportPDF --> |Generates| PrintReady["Print-Ready PDF"]
    
    Preflight --> |If issues found| Review["Manual Review Required"]

The typical print workflow:

1. Run preflight_check with target profile (e.g., x1a)
2. Review compliance errors and warnings
3. Fix issues in Illustrator
4. Export using export_pdf with appropriate settings

Usage Examples

Export Artboard as SVG

You: Export the hero artboard as SVG with outlined text

Claude: → get_artboards → convert_to_outlines → export

Export Selection as PNG

{
  "format": "png",
  "output_path": "/output/banner.png",
  "scale": 2,
  "dpi": 144
}

Export Print-Ready PDF

{
  "preset": "[PDF/X-4:2008]",
  "options": {
    "trim_marks": true,
    "marks_style": "japanese",
    "registration_marks": true,
    "color_bars": true
  }
}

Limitations and Notes

Source: README.md

Related Tools

Related Pages

Related topics: Read Tools

Utility Tools

Utility Tools in the illustrator-mcp-server provide essential辅助功能 for document validation, workflow configuration, and system integration. These tools enable quality assurance workflows, coordinate system management, and environment setup essential for reliable Illustrator automation.

Overview

The Utility Tools category encompasses three primary tools that support document preparation, validation, and configuration:

These tools serve as the foundation for print-ready production workflows, ensuring documents meet industry standards before export or submission.

Preflight Check

The preflight_check tool performs automated pre-press validation to identify issues that could compromise print quality or PDF/X compliance.

Purpose and Scope

The preflight check analyzes documents for print-critical issues including color space violations, missing assets, resolution problems, and PDF/X compliance failures. It provides a structured report with severity classification to prioritize fixes.

Source: README.md

Supported Checks

The tool performs the following validations:

Source: README.md

Parameters

Source: src/tools/utility/preflight-check.ts

Output Structure

The preflight check returns categorized results:

interface PreflightResult {
  critical: PreflightIssue[];
  warnings: PreflightIssue[];
  info: PreflightInfo[];
}

PDF/X Compliance Profiles

Source: README.md

Example Output

❌ PDF/X-1a compliance errors:
- Transparency on 3 objects (X-1a prohibits transparency)
- RGB colors found in 2 places (X-1a requires CMYK/spot only)

⚠ Warnings:
- 5 non-outlined fonts (embedding recommended)
- Image "photo_02.jpg" at 150dpi (300dpi recommended)

Source: README.md

Check Text Consistency

The check_text_consistency tool validates text content to ensure documents are production-ready and free of placeholder or inconsistent text.

Purpose and Scope

This tool detects common text issues in design documents: dummy/placeholder text that must be replaced, notation variations that indicate inconsistencies, and provides a complete text dump for LLM-driven analysis.

Source: README.md

Detection Capabilities

Source: plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md

Return Values

Source: src/tools/utility/check-text-consistency.ts

Workflow Integration

The tool integrates with the illustrator-preflight skill to provide LLM-driven deeper analysis:

flowchart TD
    A[check_text_consistency] --> B[allTexts Array]
    B --> C[LLM Analysis]
    C --> D{Typo Detection}
    C --> E{Version Mismatch}
    C --> F{Terminology Check}
    D --> G[Critical Issues]
    E --> G
    F --> G

Source: plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md

Set Workflow

The set_workflow tool configures the coordinate system and workflow mode to override auto-detected settings.

Purpose and Scope

The tool enables manual override of the automatic coordinate system detection, ensuring consistent behavior regardless of document type. This is essential when working with documents that have unconventional settings or when specific coordinate conventions are required.

Source: README.md

Coordinate System Detection

The server automatically detects coordinate systems based on document type:

Source: README.md

Workflow Modes

Parameters

Behavior

When set_workflow is called:

1. The specified mode overrides auto-detection
2. All subsequent coordinate conversions use the configured system
3. Tools like convert_coordinate respect the active workflow mode

flowchart LR
    A[Document Opens] --> B{User calls set_workflow?}
    B -->|No| C[Auto-detect coordinate system]
    B -->|Yes| D[Use specified mode]
    C --> E[Return coordinates]
    D --> E

Source: src/tools/utility/set-workflow.ts

Set Illustrator Version

The set_illustrator_version tool configures the target Illustrator version for script generation compatibility.

Purpose and Scope

Different Illustrator versions support different scripting APIs and features. This tool ensures generated scripts target the correct version, preventing compatibility issues when working with legacy or specific version requirements.

Source: src/tools/utility/set-illustrator-version.ts

Supported Versions

Parameters

Utility Tool Architecture

flowchart TB
    subgraph "Utility Tools"
        PC[preflight_check]
        CTC[check_text_consistency]
        SW[set_workflow]
        SIV[set_illustrator_version]
    end
    
    subgraph "Supporting Infrastructure"
        GSI[get_separation_info]
        GOI[get_overprint_info]
        CC[convert_coordinate]
    end
    
    PC --> GSI
    PC --> GOI
    PC --> CTC
    SW --> CC
    SIV --> PC
    
    subgraph "Output"
        Reports[Preflight Reports]
        TextDump[Text Analysis]
        Config[Workflow Config]
    end
    
    PC --> Reports
    CTC --> TextDump
    SW --> Config

Integration with illustrator-preflight Skill

The Utility Tools are orchestrated by the illustrator-preflight skill for comprehensive pre-press workflows:

sequenceDiagram
    participant User
    participant Skill
    participant Tools
    
    User->>Skill: Run preflight check
    Skill->>Tools: preflight_check
    Skill->>Tools: get_overprint_info
    Skill->>Tools: check_text_consistency
    Tools-->>Skill: Results
    Skill->>Skill: Analyze & Classify
    Skill->>Tools: get_separation_info (conditional)
    Tools-->>Skill: Plate info
    Skill-->>User: Structured Report

Source: plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md

Preflight Workflow Steps

The skill executes a 7-step comprehensive pre-press workflow:

Source: README.md

Common Usage Patterns

Pre-Delivery Validation

// Run comprehensive preflight before submission
const preflight = await preflight_check({
  target_pdf_profile: "x1a",
  min_dpi: 300
});

const overprint = await get_overprint_info();
const textCheck = await check_text_consistency();

Workflow Configuration for Print

// Configure for CMYK print workflow
await set_workflow({ mode: "print" });

// All subsequent operations use document coordinates
const coords = await convert_coordinate({
  x: 100,
  y: 100,
  from: "artboard",
  to: "document"
});

Text Content Audit

const textResult = await check_text_consistency();

// Check for placeholders
if (textResult.hasPlaceholder) {
  console.log("Replace placeholder text:", textResult.placeholderMatches);
}

// LLM-driven analysis of all text
const allText = textResult.allTexts.map(t => t.content);

Error Handling and Limitations

Known Constraints

Source: README.md

Best Practices

1. Always run preflight_check before print submission
2. Use check_text_consistency to catch placeholder text before delivery
3. Set workflow mode explicitly when working with mixed document types
4. Configure Illustrator version when targeting specific deployment environments

Related Pages

Related topics: Execution Flow, Modify Tools

Coordinate Systems

Adobe Illustrator uses two distinct coordinate systems with different origins and Y-axis orientations. The illustrator-mcp-server provides unified coordinate handling that automatically detects the appropriate system based on the document type, while also allowing manual override when needed.

Overview

Coordinate systems in Illustrator determine how positions are interpreted across the application. The illustrator-mcp-server abstracts the complexity of coordinate transformations, allowing AI assistants to work with positions in a consistent manner regardless of the underlying document configuration.

The server automatically detects which coordinate system is in use based on document properties and includes coordinate system information in all tool responses via the coordinateSystem field.

Coordinate System Types

The illustrator-mcp-server supports two coordinate systems:

Document Coordinate System

The document coordinate system uses Illustrator's native coordinate space:

• Origin: Bottom-left corner of the document
• Y-Axis: Positive values extend upward
• Application: CMYK documents, print workflows
• Behavior: Matches what print designers expect from traditional illustration software

This system is detected when the document color mode is set to CMYK.

Artboard Web Coordinate System

The artboard-web coordinate system uses a web-style coordinate space:

• Origin: Top-left corner of the active artboard
• Y-Axis: Positive values extend downward
• Application: RGB documents, web and digital workflows
• Behavior: Matches browser and screen coordinate conventions

This system is detected when the document color mode is set to RGB.

Auto-Detection Mechanism

The server automatically determines the appropriate coordinate system based on document properties. This detection happens on session start and when documents change.

graph TD
    A[Document Open] --> B{Color Mode?}
    B -->|CMYK| C[Use document System]
    B -->|RGB| D[Use artboard-web System]
    C --> E[Set coordinateSystem Field]
    D --> E
    E --> F[Cache Detection Result]

Detection Signals

The auto-detection process analyzes multiple document signals:

Source: src/tools/session.ts:40-55

Detection Caching

To optimize performance, the auto-detection result is cached:

// Cache key structure
autoDetectCache = {
  documentId: string,
  colorMode: string,
  timestamp: number
}

Source: src/tools/session.ts:20-35

The cache is invalidated when:

1. The document changes
2. The color mode changes
3. The artboard changes
4. Manual override via set_workflow is called

Manual Override with set_workflow

When auto-detection does not produce the desired behavior, use the set_workflow tool to explicitly set the coordinate system:

{
  "tool": "set_workflow",
  "parameters": {
    "mode": "web"
  }
}

Available Workflow Modes

When set_workflow is called with a specific mode:

1. The auto-detection cache is bypassed
2. All subsequent coordinate operations use the specified system
3. The coordinateSystem field reflects the manually set value

Coordinate Conversion

The convert_coordinate tool transforms points between coordinate systems within the active document.

Tool Parameters

Conversion Behavior

// Internal mapping to Illustrator constants
const fromMap = {
  "artboard": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,
  "document": CoordinateSystem.DOCUMENTCOORDINATESYSTEM
};

const toMap = {
  "artboard": CoordinateSystem.ARTBOARDCOORDINATESYSTEM,
  "document": CoordinateSystem.DOCUMENTCOORDINATESYSTEM
};

Source: src/tools/read/convert-coordinate.ts:1-10

Conversion Example

Converting a point from artboard (web) coordinates to document (Illustrator native) coordinates:

{
  "tool": "convert_coordinate",
  "parameters": {
    "point": { "x": 100, "y": 200 },
    "from": "artboard",
    "to": "document"
  }
}

Response includes the converted coordinates and system identifiers:

{
  "x": 100,
  "y": 868,  // Y inverted based on artboard height
  "from": "artboard",
  "to": "document"
}

Y-Axis Transformation

The conversion handles Y-axis inversion automatically:

The artboard height is obtained from the active artboard rectangle to ensure accurate transformation.

Coordinate System in Tool Responses

All tool responses include a coordinateSystem field indicating which system is currently active:

{
  "success": true,
  "uuid": "abc123",
  "coordinateSystem": "artboard-web"
}

This field helps AI assistants interpret position values correctly and choose appropriate coordinate systems for subsequent operations.

Workflow Detection Logic

The detectWorkflow function in session.ts determines the appropriate coordinate system based on document signals:

export function detectWorkflow(signals: DocumentSignals): WorkflowHint {
  const { colorMode, rulerUnits, rasterEffectResolution, colorProfile } = signals;

  const isCMYK = colorMode === 'CMYK';
  const isRGB = colorMode === 'RGB';
  const isPixelUnit = rulerUnits === 'px';
  const isPrintUnit = ['mm', 'cm'].includes(rulerUnits);
  
  // Decision logic based on signals
  // Returns WorkflowHint with detectedWorkflow and recommendedCoordinateSystem
}

Source: src/tools/session.ts:40-65

The detection considers:

• Primary signal: Color mode (CMYK vs RGB)
• Supporting signals: Ruler units, raster resolution, color profile
• Consistency check: Verify all signals align

Best Practices

When to Use `document` System

• Working with CMYK print documents
• Creating content for physical output
• Using print-specific measurements (mm, cm, inches)

When to Use `artboard-web` System

• Working with RGB web documents
• Creating content for digital display
• Using pixel-based measurements

When to Override with `set_workflow`

• Document auto-detection fails
• Mixed workflow (e.g., RGB document for print preview)
• Specific AI task requirements

Coordinate Conversion Strategy

1. Determine the current coordinate system from tool response
2. Use matching coordinates for the active system
3. Convert when bridging between systems
4. Cache conversion results for repeated operations

Related Pages

Related topics: Getting Started

Development Guide

This document serves as the comprehensive development guide for illustrator-mcp-server, a Model Context Protocol (MCP) server that enables AI assistants like Claude to read, manipulate, and export Adobe Illustrator design data. The server provides 26 tools for automation and inspection of Illustrator documents across macOS and Windows platforms.

Project Overview

The illustrator-mcp-server acts as a bridge between AI assistants and Adobe Illustrator's ExtendScript scripting engine. It leverages the MCP SDK to expose Illustrator functionality as discrete tools that AI can invoke through natural language commands.

Key Characteristics

Project Structure

The repository follows a standard Node.js TypeScript project structure with MCP-specific components:

illustrator-mcp-server/
├── src/
│   ├── tools/
│   │   └── registry.ts          # Tool registration and definition
│   └── prompts/
│       └── registry.ts          # Prompt templates for AI interaction
├── dist/                        # Compiled JavaScript output
├── test/
│   └── e2e/
│       └── smoke-test.ts        # End-to-end smoke tests
├── manifest.json                # MCP extension manifest
├── server.json                  # MCP server configuration
├── package.json                 # npm package configuration
└── tsconfig.json                # TypeScript configuration

Development Environment Setup

Prerequisites

Installation

git clone https://github.com/ie3jp/illustrator-mcp-server.git
cd illustrator-mcp-server
npm install

The npm install command installs both runtime dependencies and development dependencies as defined in package.json.

Source: package.json:1-50

Build Process

npm run build

The build command compiles TypeScript source files from src/ to JavaScript in the dist/ directory. The pre-publish lifecycle hook ensures the build completes before any publish operation:

"prepublishOnly": "npm run build"

Source: package.json:14 package.json:18

TypeScript Configuration

The project uses TypeScript for type safety and modern JavaScript features. The tsconfig.json defines compilation targets and module resolution:

Key Configuration Options

Tool Registration System

The MCP server exposes tools through a registration system defined in src/tools/registry.ts. Each tool corresponds to a specific Illustrator operation.

Tool Categories

The server provides 26 tools organized into functional categories:

Source: manifest.json:15-30

Tool Registration Flow

graph TD
    A[Start] --> B[Load tool definitions from registry.ts]
    B --> C[Parse ExtendScript handlers]
    C --> D[Register with MCP SDK]
    D --> E[Server starts listening for requests]
    E --> F[Tool invocation received]
    F --> G[Execute ExtendScript in Illustrator]
    G --> H[Return JSON response to AI]

Adding New Tools

To add a new tool to the server:

1. Define the tool handler in the appropriate source file within src/
2. Register the tool in src/tools/registry.ts with:

• Tool name and description
• Parameter schema (JSON Schema format)
• ExtendScript handler function

1. Update manifest.json if exposing through MCP extension format

Prompt System

The prompt registry (src/prompts/registry.ts) contains templates that guide the AI's behavior when interacting with Illustrator through the MCP server. Prompts are particularly important for:

• Preflight workflows: Structured validation steps for print-ready documents
• Design token extraction: Systematic extraction of design system values
• Text consistency checking: Pattern recognition for placeholder and inconsistency detection

Preflight Prompt Structure

The preflight skill uses a structured prompt approach:

graph LR
    A[Start Preflight] --> B[Step 1: Asset Checks]
    B --> C[Step 2: Text Checks]
    C --> D[Step 3: Report Generation]
    D --> E[Critical Issues]
    D --> F[Warnings]
    D --> G[Info Items]

Source: plugins/illustrator-preflight/skills/illustrator-preflight/SKILL.md:1-50

Testing

Unit Tests

npm test

The project uses Vitest for unit testing. Test files are located alongside source files with the .test.ts or .spec.ts extension.

Source: package.json:15

End-to-End Smoke Tests

npx tsx test/e2e/smoke-test.ts

The E2E smoke test requires Adobe Illustrator to be running. It performs:

Test Statistics:

• 182 test cases across 10 phases
• Validates all tool registrations
• Confirms coordinate system behavior for different document types

Source: README.md:1-50

Verification with MCP Inspector

npx @modelcontextprotocol/inspector npx illustrator-mcp-server

The MCP Inspector tool allows verification of the server configuration and tool registration without running a full AI client.

Build Outputs

Standard Build

npm run build

Outputs compiled JavaScript to the dist/ directory:

• dist/index.js - Main server entry point
• dist/bundle.cjs - CommonJS bundle for MCP packaging

MCP Extension Package

npm run pack:mcpb

This command:

1. Builds the project
2. Installs production dependencies only (--omit=dev)
3. Packs the server using the Anthropic MCPB packager
4. Reinstalls development dependencies

Output: illustrator-mcp-server.mcpb - Distributable extension package for Claude Desktop

Source: package.json:19

Release Process

npm run release

The release pipeline executes:

1. npm run build - Compile TypeScript
2. npm test - Run unit tests
3. git push - Push to remote
4. git push --tags - Publish version tags

Source: package.json:20

Server Configuration

MCP Server Manifest

The server.json defines the MCP server metadata:

{
  "name": "io.github.ie3jp/illustrator-mcp-server",
  "description": "Read, manipulate, and export Adobe Illustrator design data. 26 tools. macOS | Windows.",
  "version": "1.2.6",
  "packages": [{
    "identifier": "illustrator-mcp-server",
    "version": "1.2.6",
    "transport": { "type": "stdio" }
  }]
}

Source: server.json:1-25

Claude Desktop Integration

For Claude Desktop integration, add to the MCP configuration:

{
  "mcpServers": {
    "illustrator": {
      "command": "npx",
      "args": ["illustrator-mcp-server"]
    }
  }
}

Note: If using a Node.js version manager (nvm, mise, fnm), use the full path to npx:

```json

"command": "/full/path/to/npx"

```

Dependencies

Runtime Dependencies

Source: package.json:33-35

Development Dependencies

Source: package.json:37-41

ExtendScript Integration

The server communicates with Adobe Illustrator via ExtendScript (JavaScript for Adobe applications). Each tool maps to one or more ExtendScript commands that execute within Illustrator's scripting environment.

macOS Implementation

On macOS, the server uses AppleScript to invoke Illustrator:

tell application "Adobe Illustrator"
    -- ExtendScript code executes here
end tell

Windows Implementation

On Windows, the server uses PowerShell COM automation:

$illustrator = New-Object -ComObject Illustrator.Application

Source: README.md:80-90

Known Development Constraints

Source: README.md:95-100

Contributing

When contributing to the project:

1. Follow TypeScript strict mode - Enable all type checking options
2. Add unit tests for new tools in the test/ directory
3. Update manifest.json if the tool count changes
4. Document in SKILL.md for skills that require structured prompts
5. Test E2E smoke tests before submitting pull requests

License

The project is licensed under the MIT License. See the LICENSE file for full terms.

Doramagic Pitfall Log

Doramagic extracted 8 source-linked risk signals. Review them before installing or handing real data to the project.

1. Configuration risk: Configuration risk needs validation

• Severity: medium
• Finding: Configuration risk is backed by a source signal: Configuration risk needs validation. Treat it as a review item until the current version is checked.
• User impact: Users may get misleading failures or incomplete behavior unless configuration is checked carefully.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.host_targets | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | host_targets=mcp_host, claude, claude_code

2. Capability assumption: README/documentation is current enough for a first validation pass.

• Severity: medium
• Finding: README/documentation is current enough for a first validation pass.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: capability.assumptions | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | README/documentation is current enough for a first validation pass.

3. Project risk: Project risk needs validation

• Severity: medium
• Finding: Project risk is backed by a source signal: Project risk needs validation. Treat it as a review item until the current version is checked.
• User impact: The project should not be treated as fully validated until this signal is reviewed.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: Source-linked evidence: https://github.com/ie3jp/illustrator-mcp-server/issues/35

4. Maintenance risk: Maintainer activity is unknown

• Severity: medium
• Finding: Maintenance risk is backed by a source signal: Maintainer activity is unknown. Treat it as a review item until the current version is checked.
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | last_activity_observed missing

5. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: downstream_validation.risk_items | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium

6. Security or permission risk: no_demo

• Severity: medium
• Finding: no_demo
• User impact: The project may affect permissions, credentials, data exposure, or host boundaries.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: risks.scoring_risks | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | no_demo; severity=medium

7. Maintenance risk: issue_or_pr_quality=unknown

• Severity: low
• Finding: issue_or_pr_quality=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | issue_or_pr_quality=unknown

8. Maintenance risk: release_recency=unknown

• Severity: low
• Finding: release_recency=unknown。
• User impact: Users cannot judge support quality until recent activity, releases, and issue response are checked.
• Recommended check: Open the linked source, confirm whether it still applies to the current version, and keep the first run isolated.
• Evidence: evidence.maintainer_signals | art_a1317fdd77604ec08836eb8f2de42a23 | https://github.com/ie3jp/illustrator-mcp-server#readme | release_recency=unknown

Community Discussion Evidence

Doramagic exposes project-level community discussion separately from official documentation. Review these links before using illustrator-mcp-server with real data or production workflows.

• Community source 1 - github / github_issue
• v1.4.0 - github / github_release
• v1.3.2 - github / github_release
• v1.3.1 - github / github_release
• v1.3.0 - github / github_release
• v1.2.12 - github / github_release
• v1.2.11 - github / github_release
• v1.2.9 - github / github_release
• v1.2.8 - github / github_release
• v1.2.7 - github / github_release
• Community source 11 - x / searxng_indexed
• Configuration risk needs validation - GitHub / issue