io.github.jimprivate/idml-mcp

idmlkit

The AI-native toolkit for Adobe InDesign files (IDML) — parse, summarize, and safely write back. No InDesign required.

AI tools have transformed how we write code and build web pages, but print and layout designers have largely been left out: the InDesign ecosystem has no AI-ready open interface. Existing InDesign MCP servers all remote-control a running InDesign instance — which means a license, a desktop, and an open app for every operation.

idmlkit takes the other road: it works directly on .idml files (InDesign's open, XML-based interchange format). That means it runs anywhere Node.js runs — servers, CI pipelines, Linux, a designer's laptop — with nothing from Adobe installed.

JSON data in ──► idmlkit ──► perfectly laid-out IDML out ──► open in InDesign / print

Design philosophy: the AI never touches the XML

LLMs are great at understanding a document and deciding what should change, and terrible at hand-editing 5,000 lines of layout XML without breaking it. So idmlkit splits the work:

• Deterministic code parses the package and produces a compact, LLM-friendly summary (pages, frames, stories as indexed text runs, image links, styles) — a few hundred tokens instead of megabytes of XML.
• Write-back is surgical: replacing a text run or relinking an image rewrites only that one element via targeted string surgery. Everything else — geometry, styles, the XML formatting itself — is preserved byte-for-byte (enforced by tests). The AI physically cannot corrupt your layout.

Validated against real InDesign 2025 exports: on Adobe's official Flex Layout sample (14.5 MB, with a single 20 MB spread), summarize runs in under half a second and a text edit changes exactly one zip entry — every other entry verified byte-identical by CRC.

Packages

Quick start

npm install
npm run build
node scripts/make-sample-idml.mjs   # generates examples/sample.idml

CLI

$ node packages/idmlkit/dist/cli.js summary examples/sample.idml
Pages: 1  Spreads: 1
Story u123 (11 words, 2 runs): Spring Catalog 2026 Fresh arrivals for the new season…
Image link u202: file:/images/hero.jpg
Paragraph styles: $ID/NormalParagraphStyle, Headline, Body

$ node packages/idmlkit/dist/cli.js set-text examples/sample.idml u123 0 "Summer Sale 2026" -o out.idml
$ node packages/idmlkit/dist/cli.js relink out.idml u202 "file:/images/summer.jpg"

MCP server (Claude Code / Claude Desktop)

{
  "mcpServers": {
    "idml": {
      "command": "node",
      "args": ["<repo>/packages/idml-mcp/dist/server.js"]
    }
  }
}

Then ask Claude things like "Summarize catalog.idml and replace every 2025 date with 2026" — it will use these tools:

Library

import { IdmlDocument, summarizeDocument, setStoryRunText } from "idmlkit";

const doc = await IdmlDocument.open("catalog.idml");
console.log(summarizeDocument(doc));      // LLM-friendly JSON
setStoryRunText(doc, "u123", 0, "New headline");
await doc.save("catalog-updated.idml");

Use cases

• Database publishing: fill a designed template with product data — thousands of catalog pages, price lists, or menus without opening InDesign once.
• Localization: extract every text run with its styles, translate, write back safely.
• Agent workflows: let Claude read a layout, reason about its content, and apply text/image updates as part of a larger pipeline.

Roadmap

• [x] Read IDML packages, LLM-friendly summaries
• [x] Safe text run replacement and image relinking
• [x] MCP server (stdio)
• [ ] Page → frame mapping with geometry (which frame is where)
• [ ] Template fill: apply a JSON data object to a tagged template in one call
• [ ] Story-level structured diff (what changed between two IDML files)
• [ ] Overflow heuristics (warn when new text likely won't fit its frame)
• [ ] Real-world IDML corpus tests (CC 2018–2026 exports)

Development

npm install
npm run build     # tsc project references
npm test          # vitest — includes byte-for-byte preservation tests

License

MIT. Not affiliated with or endorsed by Adobe. "Adobe" and "InDesign" are trademarks of Adobe Inc., used here only to describe compatibility.