Adobe InDesign

[indesign-nutria-mcp]

Say "Create an A4 document with 5 pages, add a red circle on page 3" — and it happens.
The most comprehensive MCP server for Adobe InDesign. 199 tools. 35 handlers. Full DOM coverage.

[Demo video]
_{⚡ Click for a quick demo · v1.1.0 release}

[license] [npm] [tools] [tests] [CI] [node] [indesign]

Published to npm as indesign-nutria-mcp. Your agent starts it with npx -y indesign-nutria-mcp — see Quick Start. InDesign still runs on your machine: the server reaches it over a local bridge, and nothing leaves the box.

🚀 Why This Exists

InDesign automation has been broken for 20 years. ExtendScript is ancient. CEP panels are over-engineered. UXP scripting requires a CS degree. You just want AI to do the layout.

This MCP server fixes that. Clone it, point your agent at it, and InDesign is yours to drive like a puppeteer.

🆚 MCP vs The Old Ways

✨ What It Can Do

📝 Text & Typography (27 tools)

Create frames, set content, apply paragraph/character styles, control formatting, search with GREP, find/replace, apply fonts, set columns, insets, auto-size, vertical justification, drop caps, keep options, hyphenation, tabs, paragraph rules, text wrap, baseline, linking/unlinking.

🎨 Shapes & Objects (20 tools)

Rectangles, ellipses, polygons, lines, groups, anchored objects — create, modify, delete, list, arrange.

🖼️ Images (5 tools)

Place from disk, query metadata, fit/proportional, adjust brightness/contrast, relink.

🎭 Colors & Swatches (6 tools)

CMYK/RGB/LAB/spot swatches, ink list, gradients, apply to fill/stroke.

📄 Pages & Documents (15 tools)

Create, open, save, close, getInfo, listOpen — plus page add/delete/duplicate/move/getInfo/listAll/applyMaster, sections.

📊 Tables (20 tools)

Create, set cells, add/delete rows/columns, merge/split, alignment, fills, strokes, insets, header/footer, row/column sizing, table styles, cell styles.

🧬 Styles (10 tools)

Paragraph, character, object styles — create, list, duplicate, delete, apply.

🏗️ Masters & Books (10 tools)

Master spreads — create, duplicate, apply, delete, list, getPages. Books — list, open, getDocuments, synchronize.

📤 Export (9 tools)

PDF, EPUB, HTML, JPG, PNG, package — plus preflight, font/swatch/table lists, and script_run() for custom ExtendScript.

🔍 Find & Replace (5 tools)

GREP find/replace, format-aware find/replace.

🔄 Transform (5 tools)

Align, distribute, rotate, scale, flip.

🔗 Interactive (5 tools)

Hyperlinks, buttons, cross-reference anchors.

📚 References (10 tools)

Footnotes, endnotes, cross-references, index entries/topics/generation.

📋 Lists (6 tools)

Define, apply to paragraph/selection, remove, restart numbering.

🧩 XML & Data Merge (11 tools)

XML tags, import/export, data merge with CSV/TSV/XML sources.

🔧 Other

Layers, effects (drop shadow, feather, transparency), TOC, sections, undo/redo, undo groups.

🧠 Included AI Skills

Ten skills ship with the repo, auto-loaded by trigger keywords when you use any AI agent:

🏗️ Architecture

┌─────────────────────┐       STDIO        ┌──────────────────────┐     WebSocket     ┌──────────────────┐│  Any AI Agent       │ ◄────────────────► │  indesign-nutria-mcp │ ◄───────────────► │  Adobe InDesign   ││  (Claude, OpenCode, │                    │  (Node.js MCP Server) │     port 8120     │  + UXP Plugin     ││   Cursor, etc.)     │                    │  35 handlers         │                    │  + ExtendScript    │└─────────────────────┘                    │  199 tools           │                    └──────────────────┘                                           │  10 AI skills        │                                           └──────────────────────┘

Two ways to reach InDesign

The MCP protocol always speaks stdio. Only the last hop differs, and you pick one per platform:

Both are supported. The plugin is the richer path (it also emits change events); the proxy exists for setups where you cannot or do not want to load a UXP panel. See WINDOWS.md for the Windows bridge and start-bridge.sh for the macOS one.

Full breakdown: the four macOS processes, the request lifecycle, the error contract and the trust boundaries are in docs/architecture.md.

Full Handler Catalog

tests/contract/toolInventory.test.ts pins this number, so the table cannot drift from the code without failing CI.

Verified end-to-end against InDesign 2026 (21.3) on the plugin-free macOS path: MCP stdio → WebSocket bridge → JXA proxy → InDesign, creating a document, adding a text frame, reading it back, and closing.

Closing documents from an agent? document_close defaults to saveOptions: "no" — the only value that cannot raise a modal dialog. "ask" opens a save prompt, and "yes" opens a Save As dialog for a document that was never saved; both block the script until the bridge times out. Save first with document_save { filePath }, then close.

MCP Resources

🎯 Use Cases

🏢 Agency Production

"Create a 200-page catalog from this CSV. Product name in 14pt Arial Bold, price in 12pt Arial Regular, description in 10pt. Add a red 'SALE' badge on page 1, 50, 100, 150. Export as PDF."

📚 Book Publishing

"Import this Word document. Map Heading 1 to 'Chapter Title' style, Normal to 'Body Text'. Add running headers with page numbers. Generate a TOC. Export to PDF with crop marks."

🎨 Creative Automation

"Take this InDesign template and generate 50 variations with different colors and text from this spreadsheet. Export each as a separate PDF."

🏭 Print Production

"Check all 200 files for missing fonts and broken links. Fix them. Export as PDF/X-1a."

🔄 Continuous Publishing

"Every morning at 8am, update the daily newspaper template with fresh content from our CMS, preflight, and upload to the web server."

⚡ Quick Start (30 seconds)

Two halves: the server your agent runs — one line from npm, no clone and no build — and the bridge that reaches InDesign on this machine.

1️⃣ Connect InDesign

The server listens on 127.0.0.1:8120; something still has to drive InDesign. Pick by platform:

macOS — with the UXP panel (also emits change events)

1. Open UXP Developer Tool
2. Load the plugin/ directory — it ships in this repository, so clone it once: git clone https://github.com/nutriandrea/adobe-indesign-mcp (no build step)
3. Open the MCP Bridge panel — it connects on its own

macOS — without the panel

git clone https://github.com/nutriandrea/adobe-indesign-mcpcd adobe-indesign-mcpnpm install            # gives the proxy its `ws` dependency; nothing to build./start-bridge.sh      # launches InDesign, then the JXA proxy

Windows — no bridge process. The COM bridge drives InDesign in-process, so Windows needs neither the clone nor a second process; it is enabled by the env var in the config you use in step 2 (see examples/claude-desktop.windows.json). See WINDOWS.md for the details and caveats.

2️⃣ Connect your AI agent

Both hosts start the same published package — nothing to clone, nothing to build.

Claude Desktop:

{  "mcpServers": {    "indesign": {      "command": "npx",      "args": ["-y", "indesign-nutria-mcp"]    }  }}

OpenCode (project opencode.json, or the same block in ~/.config/opencode/opencode.json):

{  "mcp": {    "servers": {      "indesign": {        "type": "local",        "command": ["npx", "-y", "indesign-nutria-mcp"]      }    }  }}

On OpenCode the servers live under mcp.servers, not mcpServers, and the command is an array — that is the documented V2 shape.

Ready-made files for Claude Desktop, Cursor and Claude Code — including the Windows COM variant — are in examples/. Each one is copy-paste.

3️⃣ Start creating

🤖 "Create a landscape A3 document with 3 pages."🤖 "Add a blue rectangle covering the top half of page 1."🤖 "In the rectangle, add text 'Hello World' in white, Arial Bold 72pt."🤖 "Export page 1 as JPG."

📝 Notes for MCP client developers

Building a custom client (script, harness, test runner) against this server? Two lessons from real-world integration:

Every message is a single-line JSON-RPC object terminated by \n; there is no framing beyond the newline.

🆕 What's New in v1.6.0

Fixed

Added

⚙️ Configuration

All settings have defaults — zero config required. To customize, copy .env.example to .env or pass a JSON file; environment variables win over the file:

BRIDGE_PORT=8120            # WebSocket port the UXP plugin connects toHTTP_BRIDGE_ENABLED=false   # optional REST fallback bridgeHTTP_BRIDGE_PORT=3000SERVER_TRANSPORT=stdio      # stdio | websocketLOG_LEVEL=info              # debug | info | warn | errorCOM_BRIDGE_ENABLED=false    # Windows only: drive InDesign over COM, no pluginRESPONSE_ENVELOPE_SUCCESS=false  # wrap successful results as { ok: true, ... }

The plugin-free macOS proxy takes its own variables:

INDESIGN_APP="Adobe InDesign 2026"     # matches your installed versionBRIDGE_WS_URL=ws://127.0.0.1:8120BRIDGE_TIMEOUT_MS=120000               # a long export is not a hangBRIDGE_RECONNECT_DELAY_MS=3000

Precedence: environment variables > JSON config file > defaults. Invalid values are ignored, never fatal.

🪟 Windows

Two ways to run on Windows: the standard UXP plugin flow (identical to macOS) or the new opt-in COM bridge that needs no plugin at all. See WINDOWS.md.

📦 Project Structure

├── src/│   ├── server/          # MCP server (STDIO transport)│   ├── bridge/          # WebSocket bridge, ScriptExecutor, protocol, COM executor│   ├── handlers/        # 35 handler modules (199 tools)│   ├── schemas/         # Zod parameter schemas│   ├── core/            # Session tracking│   ├── types/           # TypeScript definitions│   └── utils/           # Config, logger, security, JSON polyfill├── plugin/              # UXP panel (index.html, index.js, manifest.json)├── examples/            # Copy-paste client configs (Claude Desktop, Cursor, Claude Code)├── mcpb/                # MCP Bundle manifest (npm run build:mcpb packs the archive)├── server.json          # MCP Registry manifest (generated from package.json)├── llms.txt             # llms.txt index for agents and directories├── bridge-proxy.mjs     # Plugin-free macOS proxy (JXA/osascript)├── jxa-driver.js        # Runs one ExtendScript inside InDesign├── start-bridge.sh      # Launches InDesign + the proxy├── skills/              # Agent-facing skills shipped with the server├── marketplace/         # Store listings that package a skill for third-party channels├── tests/               # 1131 tests (vitest)├── .opencode/skills/    # 10 AI agent skills├── docs/                # Documentation and fork audits├── media/               # Social preview, hero images├── dist/                # Compiled output└── opencode.json        # MCP configuration

📋 Requirements

🧪 Development

npm test            # Run 1131 testsnpm run test:watch  # Watch modenpm run build       # TypeScript compilenpm run lint        # ESLint

Live smoke test (macOS)

npm run smoke:macos

npm test covers the handlers, the protocol and the startup sequence, but it cannot see the seams between the four separate processes on the plugin-free macOS path. That gap is not hypothetical: 965 tests once passed against a build whose bridge never listened on its port, so every tool call failed in the field and nothing went red.

smoke:macos drives the real chain — MCP stdio → WebSocket bridge → JXA proxy → InDesign — against a running InDesign, creating a document, writing to it, reading it back, and closing it. It creates one unsaved document and cleans up after itself. It needs a desktop app, so it is not part of npm test and does not run on CI; it exits 0 with a SKIP notice if InDesign is not open.

Run it by hand before releasing a change to the bridge, the protocol, the proxy or the driver.

npm run smoke:recipes   # the live gate for the two recipes

smoke:recipes does what the unit tests cannot: it flows a long text file with recipe_flowTextStory, checks the document grew by exactly what the tool reported, calls undo once to confirm the whole flow is a single undo step, then exercises both preset paths of recipe_exportPreset. Same rules as above — needs a desktop app, exits 0 with a SKIP notice when InDesign is closed.

npm run smoke:target    # the live gate for document_id

smoke:target opens two documents and proves the thing document_id is for: a call that names the non-front document edits that document and leaves the front one alone. It then checks index targeting, that omitting document_id still acts on the front document (the additive guarantee), that an unopened target arrives as a document_not_found envelope suggesting document_listOpen, and that a hostile document_id is inert rather than executed. It closes only the documents it created, never saves, and leaves every pre-existing document untouched. Same rules as above — needs a desktop app, exits 0 with a SKIP notice when InDesign is closed.

🗺️ Roadmap

• InDesign Server — headless server support for CI/CD pipelines
• Live preview — stream InDesign canvas to agent
• Template marketplace — share and discover InDesign templates
• Natural language → layout — describe a page, get a page
• Batch PDF processing — apply changes across hundreds of files
• VSCode extension — control InDesign from your editor

📚 Deep Dives

• Architecture — the four-process macOS path, request lifecycle, error contract
• Available tools — every tool, generated from the registry
• Troubleshooting — modal hangs, port conflicts, missing fonts, blocked scripts
• Development — build, test, and the live smoke test
• Origin Story — how this project came to life
• Comparison docs — MCP vs CEP vs ExtendScript in depth
• Launch thread — social launch content

🤝 Contributing

PRs welcome! The handler pattern is designed to be simple:

1. Create src/handlers/YourHandler.ts
2. Define tools with Zod schemas
3. Register in IndesignMcpServer.ts
4. Add tests

Check CONTRIBUTING.md for details.

🙏 Acknowledgements

This server is a merge of what four people found in the field. Each of these contributions fixed something that was genuinely broken, not a cosmetic preference.

• @graydini — built the Windows COM bridge that this project runs on today: a persistent cscript process holding one live COM connection, NEVER_INTERACT so export dialogs can never block, and the path-containment hardening in validateFilePath. See PR #1 and the PR #21 merge. Also reported the InDesign 2026 API incompatibilities that shaped official Windows support: renamed and read-only ColorModel and AnchorPoint enums, and move() no longer accepting InsertionPoint targets. Earlier fixes from the same line of work landed on main as safe basedOn/pointSize reads in style listing, rich style-creation parameters, \n → paragraph-break normalization in text content, and an eval-free JSON polyfill that survives the ExtendScript sanitizer. Their branch also carried COM-specific operational knowledge — that a hung script wedges the Windows bridge with no way out, that fontFamily, italic and weight throw under COM, and that InDesign must be visibly running — now documented in WINDOWS.md and the layout skill. A file-by-file audit of what was still unmerged is in docs/forks/graydini-windows-com-bridge-audit.md.

• @advaitakelkar — diagnosed why the macOS proxy returned junk, in PR #22. Three real bugs in one report: osascript sends script results on stderr, so every successful call was read as a failure; the script was passed through shell -e quoting, which mangles any quote, backslash or newline; and the app name was hardcoded to "Adobe InDesign 2024", so every other version failed. The same work also moved the connection handshake out of app.doScript, where it was being parsed as ExtendScript. Adopted and extended — see What's New in v1.4.2.

• @ijeetu — two fixes, both easy to miss and both real. The MCP Bridge panel now connects on open instead of waiting for a Connect click, so the panel no longer looks dead when the server is already running. Earlier, they traced a parse failure in the JSON polyfill to sanitizeCode() rewriting eval( into a comment and orphaning the parentheses — the shipped wrapExtendScript already reflects that fix.

📄 License

MIT © Andrea Cacioppo

Made with ❤️ for designers who code and AI agents who design.
GitHub · Issues · Contributing