Skip to main content
Glama
InDesign UXP MCP Server

InDesign UXP MCP Server

by theloniuser

InDesign UXP MCP Server

Forked from zachshallbetter/indesign-mcp-server — rewritten to use Adobe's UXP plugin platform instead of AppleScript.

A Model Context Protocol (MCP) server that gives AI assistants direct, native control over Adobe InDesign via a UXP plugin bridge. ~130 tools covering the full InDesign feature set — documents, pages, text, graphics, styles, master spreads, books, and export.


Why UXP vs AppleScript

This server is a ground-up rewrite of the AppleScript-based indesign-mcp-server. The execution model is fundamentally different.

AppleScript (original)

UXP (this fork)

Platform

macOS only

macOS + Windows

Execution path

Node → temp JSX file → AppleScript → InDesign

Node → HTTP → WebSocket → InDesign plugin

Speed

Slow — 3 hops, disk write per call

Fast — direct in-process call

Reliability

Flaky — breaks if InDesign loses focus or system dialogs appear

Stable — not affected by focus or system state

Return values

Strings only (last evaluated expression)

Full structured JSON objects

JS version

ExtendScript (ES3 — no const, arrow functions, or async/await)

Modern JS (ES2015+ — async/await, destructuring, arrow functions)

Error messages

Cryptic AppleScript/OSA errors

Structured JSON with clear error strings

String handling

Manual escapeJsxString() for every value

JSON.stringify() throughout — safe and simple

Enums

Magic strings like 'PDF_TYPE'

Typed enums via require('indesign').ExportFormat.pdfType

Async support

Not supported — synchronous only

Native await (e.g. await doc.filePath)

Permissions

macOS Automation + Accessibility in System Settings

None beyond InDesign plugin install

Future-proofing

❌ Adobe is deprecating ExtendScript/CEP

✅ UXP is Adobe's official modern platform

The short version: The AppleScript version puppets InDesign from the outside via macOS automation, writing temp files and hoping nothing interrupts the chain. This version runs inside InDesign as a first-class plugin — faster, more reliable, cross-platform, and built on the platform Adobe is investing in going forward.


Related MCP server: InDesign MCP Server

How It Works

Claude / MCP Client
       │
       ▼
  MCP Server (Node.js)
       │  POST /execute
       ▼
  Bridge HTTP Server (port 3000)
       │  WebSocket
       ▼
  UXP Plugin (inside InDesign)
       │  runs as async IIFE with `app` in scope
       ▼
  InDesign DOM

The UXP plugin maintains a persistent WebSocket connection to the bridge. When a tool is called, the handler sends a JS code string to the bridge, which forwards it to the plugin. The plugin runs it as new Function('app', 'return (async () => { CODE })()') and returns the result as JSON.


Prerequisites

  • Adobe InDesign 2024+ (UXP plugin support required)

  • Node.js 18+

  • macOS or Windows


Setup

1. Install the UXP Plugin

Load the plugin via the UXP Developer Tool or InDesign's plugin manager:

plugin/
├── index.js        # Plugin entry point + WebSocket client
└── manifest.json   # Plugin manifest

2. Start the Bridge

# Kill any existing bridge processes
lsof -ti:3001 | xargs kill 2>/dev/null
lsof -ti:3000 | xargs kill 2>/dev/null

# Start the bridge
cd bridge && node server.js

3. Connect the Plugin

In InDesign: Window → Plugins → InDesign Bridge

The panel should show: Connected to bridge ✓

4. Start the MCP Server

npm install
npm start

5. Configure Claude

Add to ~/.claude.json (or your MCP client config):

{
  "mcpServers": {
    "indesign": {
      "command": "node",
      "args": ["/path/to/indesign-uxp-server/src/index.js"]
    }
  }
}

Testing

# Quick sanity check (4 core tools)
node tests/test-uxp-handlers.js

# Full suite (27 tests across all handler categories)
node tests/test-all-handlers.js

Current status: 27/27 passing across all handler categories.


Tools

Documents

create_document open_document save_document close_document get_document_info get_document_preferences set_document_preferences get_document_elements get_document_styles get_document_colors get_document_layers get_document_stories get_document_hyperlinks create_document_hyperlink get_document_sections create_document_section get_document_grid_settings set_document_grid_settings get_document_layout_preferences set_document_layout_preferences get_document_xml_structure export_document_xml preflight_document validate_document cleanup_document data_merge save_document_to_cloud open_cloud_document view_document

Pages & Spreads

add_page delete_page duplicate_page move_page get_page_info set_page_properties adjust_page_layout resize_page reframe_page navigate_to_page select_page zoom_to_page set_page_background create_page_guides place_file_on_page place_xml_on_page get_page_content_summary snapshot_page_layout delete_page_layout_snapshot delete_all_page_layout_snapshots list_spreads get_spread_info duplicate_spread move_spread delete_spread set_spread_properties create_spread_guides place_file_on_spread place_xml_on_spread select_spread get_spread_content_summary

Text & Tables

create_text_frame edit_text_frame create_table populate_table find_replace_text find_text_in_document

Styles & Colors

create_paragraph_style apply_paragraph_style create_character_style list_styles create_color_swatch list_color_swatches apply_color create_object_style list_object_styles apply_object_style

Graphics & Shapes

place_image get_image_info create_rectangle create_ellipse create_polygon

Layers

create_layer set_active_layer list_layers organize_document_layers

Page Items

get_page_item_info select_page_item move_page_item resize_page_item set_page_item_properties duplicate_page_item delete_page_item list_page_items

Groups

create_group create_group_from_items ungroup get_group_info add_item_to_group remove_item_from_group list_groups set_group_properties

Master Spreads

create_master_spread list_master_spreads delete_master_spread duplicate_master_spread apply_master_spread get_master_spread_info create_master_text_frame create_master_rectangle create_master_guides detach_master_items remove_master_override

Export & Output

export_pdf export_images export_epub package_document

Books

create_book open_book list_books add_document_to_book synchronize_book repaginate_book export_book package_book preflight_book print_book get_book_info set_book_properties update_all_cross_references update_all_numbers update_chapter_and_paragraph_numbers

Utility

execute_indesign_code get_session_info clear_session help


Architecture

src/
├── core/
│   ├── InDesignMCPServer.js    # MCP server, tool registration
│   ├── scriptExecutor.js       # executeViaUXP() — POSTs to bridge
│   └── sessionManager.js       # Page dimension tracking, smart positioning
├── handlers/
│   ├── documentHandlers.js
│   ├── pageHandlers.js
│   ├── textHandlers.js
│   ├── styleHandlers.js
│   ├── graphicsHandlers.js
│   ├── masterSpreadHandlers.js
│   ├── pageItemHandlers.js
│   ├── groupHandlers.js
│   ├── bookHandlers.js
│   ├── exportHandlers.js
│   └── utilityHandlers.js
├── types/                      # MCP tool schema definitions
└── utils/stringUtils.js

bridge/
└── server.js                   # HTTP (port 3000) + WebSocket (port 3001) bridge

plugin/
├── index.js                    # UXP plugin — runs code inside InDesign
└── manifest.json

tests/
├── test-uxp-handlers.js        # 4 core handler tests
└── test-all-handlers.js        # 27-test comprehensive suite

Key UXP API Notes

  • InDesign collections require .item(n) — bracket access [n] returns undefined

  • doc.filePath is async — always await it in UXP code

  • exportFile(format, path) — format arg is first (same as ExtendScript)

  • Enums via require('indesign'): ExportFormat.pdfType, ColorModel.process, etc.

  • Path strings work directly for place() and exportFile() — no UXP storage API needed

  • Code runs as async IIFE — use return to return values, await works natively


License

MIT

Available Tools

135 tools
add_document_to_bookC

Add a document to a book

Inputs: bookPath (required), documentPath (required).

add_item_to_groupB

Add a page item to an existing group

Inputs: pageIndex (required), groupIndex (required), itemIndex (required).

add_pageC

Add a new page to the document

Inputs: position, referencePage.

adjust_page_layoutC

Adjust page layout with new dimensions and margins

Inputs: pageIndex (required), width, height, bleedInside, +7 more.

apply_colorC

Apply color to an object

Inputs: objectIndex (required), colorName (required), colorType.

apply_master_spreadB

Apply a master spread to pages

Inputs: masterName (required), pageRange.

apply_object_styleB

Apply an object style to a page item

Inputs: styleName (required), itemType, itemIndex.

apply_paragraph_styleC

Apply a paragraph style to text

Inputs: styleName (required), frameIndex (required).

cleanup_documentC

Clean up document (remove unused elements)

Inputs: removeUnusedStyles, removeUnusedColors, removeUnusedLayers, removeHiddenElements.

clear_sessionB

Clear all session data including page dimensions and document information

Inputs: no named parameters.

close_documentA

Close the active document. Use saveOptions to control unsaved-changes behavior.

Inputs: saveOptions.

create_bookB

Create a new InDesign book

Inputs: filePath (required).

create_character_styleC

Create a character style

Inputs: name (required), fontFamily, fontSize, textColor, +3 more.

create_color_swatchC

Create a color swatch

Inputs: name (required), red (required), green (required), blue (required), +1 more.

create_documentC

Create a new document

Inputs: width, height, pages, facingPages, +9 more.

create_document_sectionC

Create a new section in the document

Inputs: startPage (required), sectionPrefix, startNumber, numberingStyle.

create_ellipseA

Create an ellipse on the specified page (defaults to active page in InDesign UI)

Inputs: x (required), y (required), width (required), height (required), +4 more.

create_groupC

Create a group from currently selected items

Inputs: pageIndex (required).

create_group_from_itemsC

Create a group from specific page items by their indices

Inputs: pageIndex (required), itemIndices (required).

create_layerC

Create a new layer

Inputs: name (required), visible, locked, color.

create_master_guidesB

Create guides on a master spread

Inputs: masterName (required), numberOfRows, numberOfColumns, rowGutter, +5 more.

create_master_rectangleB

Create a rectangle on a master spread

Inputs: masterName (required), x (required), y (required), width (required), +5 more.

create_master_spreadC

Create a new master spread

Inputs: name (required), baseName, namePrefix, pageColor, +1 more.

create_master_text_frameA

Create a text frame on a master spread

Inputs: masterName (required), content (required), x, y, +7 more.

create_object_styleC

Create an object style for consistent formatting

Inputs: name (required), fillColor, strokeColor, strokeWeight, +2 more.

create_page_guidesC

Create guides on a page

Inputs: pageIndex (required), numberOfRows, numberOfColumns, rowGutter, +5 more.

create_paragraph_styleC

Create a paragraph style

Inputs: name (required), fontFamily, fontSize, textColor, +4 more.

create_polygonB

Create a polygon on the specified page (defaults to active page in InDesign UI)

Inputs: x (required), y (required), width (required), height (required), +5 more.

create_rectangleB

Create a rectangle on the specified page (defaults to active page in InDesign UI)

Inputs: x (required), y (required), width (required), height (required), +5 more.

create_spread_guidesC

Create guides on a spread

Inputs: spreadIndex (required), numberOfRows, numberOfColumns, rowGutter, +5 more.

create_tableB

Create a table on the specified page (defaults to active page in InDesign UI)

Inputs: rows (required), columns (required), x, y, +5 more.

create_text_frameC

Create a text frame on the specified page (defaults to active page in InDesign UI)

Inputs: content (required), x, y, width, +8 more.

data_mergeD

Perform data merge operation

Inputs: dataSource (required), targetPage, createNewPages, removeUnusedPages.

delete_all_page_layout_snapshotsB

Delete all layout snapshots for a page

Inputs: pageIndex (required).

delete_master_spreadB

Delete a master spread

Inputs: name (required).

delete_pageB

Delete a page from the document

Inputs: pageIndex (required).

delete_page_itemC

Delete a page item

Inputs: pageIndex (required), itemIndex (required).

delete_page_layout_snapshotB

Delete the layout snapshot for a page

Inputs: pageIndex (required).

delete_spreadC

Delete a spread

Inputs: spreadIndex (required).

detach_master_itemsB

Detach master page items from a page

Inputs: pageIndex (required), itemIndex.

duplicate_master_spreadC

Duplicate a master spread

Inputs: name (required), newName (required), position.

duplicate_pageC

Duplicate a page

Inputs: pageIndex (required), position, referencePageIndex.

duplicate_page_itemC

Duplicate a page item

Inputs: pageIndex (required), itemIndex (required), x (required), y (required).

duplicate_spreadC

Duplicate a spread

Inputs: spreadIndex (required), position, referenceSpreadIndex.

edit_text_frameB

Edit an existing text frame

Inputs: frameIndex (required), content, fontSize, fontName, +2 more.

execute_indesign_codeA

Execute arbitrary JavaScript code in the InDesign UXP context. WARNING: this runs with full InDesign DOM access and can create, modify, or destroy documents. Use only as a last resort when no other tool covers the operation.

Inputs: code (required), dangerousConfirmation (required).

export_bookC

Export an entire book to various formats

Inputs: bookPath (required), outputPath (required), format.

export_document_xmlB

Export document as XML

Inputs: filePath (required), includeImages, includeStyles.

export_epubC

Export document to EPUB

Inputs: filePath (required), includeImages, includeStyles.

export_imagesB

Export pages as images

Inputs: outputPath (required), format, resolution, pages, +1 more.

export_pdfB

Export document to PDF

Inputs: filePath (required), quality, includeMarks, includeBleed, +1 more.

find_replace_textB

Find and replace text in the document

Inputs: findText (required), replaceText (required), caseSensitive, wholeWord.

find_text_in_documentC

Find text across the entire document

Inputs: searchText (required), replaceText, caseSensitive, wholeWord, +1 more.

get_book_infoC

Get detailed information about a book

Inputs: bookPath (required).

get_document_colorsA

Get all colors and swatches in the document

Inputs: includeSwatches, includeGradients, includeTints.

get_document_elementsC

Get all elements in the document

Inputs: elementType.

get_document_grid_settingsA

Get comprehensive grid settings for the document

Inputs: no named parameters.

get_document_infoC

Get information about the active document

Inputs: no named parameters.

get_document_layersC

Get all layers in the document

Inputs: includeHidden, includeLocked.

get_document_layout_preferencesB

Get layout preferences and settings for the document

Inputs: no named parameters.

get_document_preferencesC

Get document preferences and settings

Inputs: preferenceType.

get_document_sectionsB

Get all sections in the document

Inputs: no named parameters.

get_document_storiesC

Get all stories in the document

Inputs: includeOverset, includeHidden.

get_document_stylesC

Get all styles in the document

Inputs: styleType.

get_document_xml_structureC

Get XML structure of the document

Inputs: includeTags, includeElements.

get_group_infoC

Get detailed information about a group

Inputs: pageIndex (required), groupIndex (required).

get_image_infoC

Get detailed information about an image

Inputs: itemIndex.

get_master_spread_infoB

Get detailed information about a master spread

Inputs: name (required).

get_page_content_summaryB

Get a summary of content on a page

Inputs: pageIndex (required).

get_page_infoC

Get detailed information about a specific page

Inputs: pageIndex (required).

get_page_item_infoC

Get detailed information about a specific page item

Inputs: pageIndex (required), itemIndex (required).

get_session_infoA

Get current session information including page dimensions and active document

Inputs: no named parameters.

get_spread_content_summaryB

Get a summary of content on a spread

Inputs: spreadIndex (required).

get_spread_infoB

Get detailed information about a specific spread

Inputs: spreadIndex (required).

helpA

Get help information about available tools and their usage

Inputs: tool, category, format.

list_booksA

List all open books in InDesign

Inputs: no named parameters.

list_color_swatchesB

List all color swatches

Inputs: no named parameters.

list_groupsB

List all groups on a specific page

Inputs: pageIndex (required).

list_layersA

List all layers in the document

Inputs: no named parameters.

list_master_spreadsA

List all master spreads in the document

Inputs: no named parameters.

list_object_stylesA

List all object styles in the document

Inputs: no named parameters.

list_page_itemsB

List all page items on a specific page

Inputs: pageIndex (required).

list_spreadsA

List all spreads in the document

Inputs: no named parameters.

list_stylesC

List all paragraph and character styles

Inputs: styleType.

move_pageC

Move a page to a different position

Inputs: pageIndex (required), position, referencePageIndex, binding.

move_page_itemC

Move a page item to a new position

Inputs: pageIndex (required), itemIndex (required), x (required), y (required).

move_spreadC

Move a spread to a different position

Inputs: spreadIndex (required), position, referenceSpreadIndex.

open_bookC

Open an existing InDesign book

Inputs: filePath (required).

open_cloud_documentB

Open a document from Adobe Creative Cloud

Inputs: cloudDocumentId (required).

open_documentC

Open an existing document

Inputs: filePath (required).

organize_document_layersC

Organize and clean up document layers

Inputs: deleteEmptyLayers, mergeSimilarLayers, sortLayers.

package_bookC

Package a book for print production

Inputs: bookPath (required), outputPath (required), copyingFonts, copyingLinkedGraphics, +7 more.

package_documentC

Package document for printing

Inputs: outputPath (required), includeFonts, includeLinks, includeProfiles.

place_file_on_pageC

Place a file on a page

Inputs: pageIndex (required), filePath (required), x, y, +3 more.

place_file_on_spreadC

Place a file on a spread

Inputs: spreadIndex (required), filePath (required), x, y, +3 more.

place_imageB

Place an image on the specified page (defaults to active page in InDesign UI)

Inputs: filePath (required), x, y, width, +5 more.

place_xml_on_pageC

Place XML content on a page

Inputs: pageIndex (required), xmlElementName (required), x, y, +1 more.

place_xml_on_spreadC

Place XML content on a spread

Inputs: spreadIndex (required), xmlElementName (required), x, y, +1 more.

populate_tableC

Populate a table with data

Inputs: data (required), tableIndex, startRow, startColumn.

preflight_bookC

Preflight a book and optionally save the report

Inputs: bookPath (required), outputPath, autoOpen.

preflight_documentB

Run preflight on the document

Inputs: profile, includeWarnings.

reframe_pageC

Reframe (resize) a page

Inputs: pageIndex (required), x1 (required), y1 (required), x2 (required), +2 more.

remove_item_from_groupB

Remove a page item from a group

Inputs: pageIndex (required), groupIndex (required), itemIndex (required).

remove_master_overrideB

Remove override from a master page item

Inputs: pageIndex (required), itemIndex (required).

repaginate_bookC

Repaginate all documents in a book

Inputs: bookPath (required).

resize_pageC

Resize a page

Inputs: pageIndex (required), width, height, resizeMethod, +2 more.

resize_page_itemC

Resize a page item

Inputs: pageIndex (required), itemIndex (required), width (required), height (required), +1 more.

save_documentC

Save the active document

Inputs: filePath (required).

save_document_to_cloudB

Save document to Adobe Creative Cloud

Inputs: cloudName (required), includeAssets.

select_pageC

Select a page

Inputs: pageIndex (required), selectionMode.

select_page_itemC

Select a specific page item

Inputs: pageIndex (required), itemIndex (required), existingSelection.

select_spreadC

Select a spread

Inputs: spreadIndex (required), selectionMode.

set_active_layerC

Set the active layer

Inputs: layerName (required).

set_book_propertiesC

Set various properties for a book

Inputs: bookPath (required), automaticPagination, automaticDocumentConversion, insertBlankPage, +14 more.

set_document_grid_settingsC

Set comprehensive grid settings for the document

Inputs: documentGrid, documentGridColor, documentGridIncrement, documentGridSubdivision, +7 more.

set_document_layout_preferencesC

Set layout preferences for the document

Inputs: adjustLayout, adjustLayoutMargins, adjustLayoutPageBreaks, adjustLayoutRules, +3 more.

set_document_preferencesC

Set document preferences

Inputs: preferenceType (required), preferences (required).

set_group_propertiesC

Set properties of a group

Inputs: pageIndex (required), groupIndex (required), visible, locked, +1 more.

set_page_backgroundB

Set page background by creating a full-page rectangle with specified color

Inputs: pageIndex, backgroundColor, opacity.

set_page_item_propertiesC

Set properties of a page item

Inputs: pageIndex (required), itemIndex (required), fillColor, strokeColor, +3 more.

set_page_propertiesC

Set properties for a page

Inputs: pageIndex (required), label, pageColor, optionalPage, +3 more.

set_spread_propertiesC

Set properties for a spread

Inputs: spreadIndex (required), name, allowPageShuffle, showMasterItems, +4 more.

snapshot_page_layoutC

Create a snapshot of the current page layout

Inputs: pageIndex (required).

synchronize_bookB

Synchronize styles and content across all documents in a book

Inputs: bookPath (required).

ungroupB

Ungroup a group, releasing all its items

Inputs: pageIndex (required), groupIndex (required).

update_all_cross_referencesB

Update all cross references in a book

Inputs: bookPath (required).

update_all_numbersA

Update all numbers (page numbers, chapter numbers, paragraph numbers) in a book

Inputs: bookPath (required).

update_chapter_and_paragraph_numbersC

Update chapter and paragraph numbers in a book

Inputs: bookPath (required).

validate_documentC

Validate document structure and content

Inputs: checkLinks, checkFonts, checkImages, checkStyles.

view_documentB

View document information and current state

Inputs: no named parameters.

zoom_to_pageC

Zoom to fit page in view

Inputs: pageIndex (required), zoomLevel.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    C2.9/5.0

    Scored across 135 tools

    Disambiguation4/5

    Most tools have clearly distinct purposes with specific descriptions, but the large number of similar operations (e.g., multiple place_* and create_* tools) could cause slight confusion. Overall, the boundaries are well-defined.

    Naming Consistency5/5

    All tools follow a consistent verb_noun pattern (e.g., create_rectangle, get_page_info). Minor deviations like 'navigate_to_page' are still clear and do not disrupt the overall predictability.

    Tool Count2/5

    With 135 tools, the server is extremely heavy. While InDesign is a complex application, the count far exceeds typical well-scoped servers and may overwhelm agents, leading to inefficiency.

    Completeness5/5

    The tool set covers virtually all major InDesign operations, including document management, styling, page layout, books, export, and scripting. The inclusion of an execute_indesign_code tool ensures any gaps can be filled.

    Maintenance

    ActivityMaintained
    ResponsivenessOutdated data

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      C
      maintenance
      MCP server for editing Adobe InDesign via natural language in Cursor. It bridges to InDesign through AppleScript and ExtendScript, providing semantic tools for batch operations, styles, assets, and layout fixes.
      22
      MIT
    • A
      license
      Not graded
      quality
      D
      maintenance
      An MCP server that lets AI assistants drive Adobe Photoshop on Windows through ExtendScript and COM automation, offering ~122 tools for documents, layers, text, filters, color, selections, masks, layout QA, and design systems.
      3
      MIT