---
name: idmly
description: Connect idmly MCP and convert self-contained HTML designs into editable Adobe InDesign IDML files. Use for HTML-to-InDesign exports, including reports, presentations and editorial layouts created with an AI tool.
---

# idmly: HTML design to editable InDesign

idmly converts a finished, self-contained HTML design into a native `.idml`
file. Text frames, paragraph and character styles, vector charts, tables and
linked images remain editable in InDesign. It also opens in Affinity Publisher.
idmly exports files; it does not control a running copy of InDesign.

Any design's two most detailed pages can be converted free, with no account or license key.
A $49 lifetime license covers full-document conversions through the website
and MCP. Trial limits apply; do not split a document to bypass them.

The full input rules (file, page detection, what becomes native, what is left
out, every error and its fix) are at https://www.idmly.com/what-converts.html.

## Connect the user's AI tool

If idmly is already connected, reuse it. Otherwise use the setup supported by
the user's current client, preserving other MCP servers and configuration.
If the client cannot be identified, ask which AI tool they want to connect.
Connecting the server does not authorize uploading a design or buying a license.

The local server requires Node.js 20 or newer. The npm package is `idmly-mcp`.

### Claude Code

```sh
claude mcp add idmly -- npx -y idmly-mcp
```

### Cursor, Windsurf or Claude Desktop

Merge this server entry into the client's MCP configuration (`mcp.json` or
`claude_desktop_config.json`), using that client's supported location and scope:

```json
{
  "mcpServers": {
    "idmly": {
      "command": "npx",
      "args": ["-y", "idmly-mcp"]
    }
  }
}
```

### Codex CLI

Add to the user's MCP configuration in `~/.codex/config.toml`:

```toml
[mcp_servers.idmly]
command = "npx"
args = ["-y", "idmly-mcp"]
```

For other Codex surfaces, use their supported MCP settings rather than assuming
that CLI configuration applies. If configuration changes require restarting
or reconnecting the client, tell the user. Call `idmly_status` when the tool
becomes available; it checks reachability and whether a key is configured.
Key presence is not license validation: validation happens on conversion.

### Remote clients

Clients that support remote Streamable HTTP MCP can connect to:

```text
https://idmly-production.up.railway.app/mcp
```

No authorization header is needed for the trial. Licensed clients use
`Authorization: Bearer <license key>` in their secure connection settings.
Check that the current client supports this connection type before configuring it.

In claude.ai or Claude Desktop the path is Customize → Connectors → Add custom
connector: paste the URL, choose **No sign-in**, then under **Request headers**
pick `authorization` and enter `Bearer <license key>` (the word Bearer, a space,
then the key). Claude sends the value exactly as typed and adds no scheme; the
engine also accepts a bare key. If the dialog shows no Request headers section,
that beta has not reached the account yet: use the local server instead.

## Convert an HTML design

When the user asks to convert a design, call `convert_to_indesign` with exactly
one input:

- `path`: the local `.html` file (local server only).
- `html`: the complete HTML document as a string.
- `url`: a direct public HTTPS link to the HTML file. Claude and ChatGPT share
  links are app pages; use the downloaded HTML instead.

For the local server, `out_dir` and `name` can select the output folder and
base filename. `platform` can be `mac` or `win` for the computer that will open
the file. Do not overwrite an existing output the user wants to keep.

The local server writes the `.idml` and returns its path, converted page count,
required fonts and a geometry check. With images, it returns a folder containing
the `.idml` and `Links/`; keep them together. Trial output ends in `-trial.idml`.
The remote server returns a one-time download link, not a local file path;
fetch it promptly when authorized. It expires after ten minutes or one download.

Tell the user where the file is, whether it is a two-page trial or a full
conversion, and which fonts need to be active. Do not claim to have visually
verified it in InDesign unless that check actually happened.

## Prepare HTML that converts well

- Use fixed-size `.page` or `.slide` blocks. A4 is commonly 794 x 1123 px;
  Letter is 816 x 1056 px. A two-page reader spread uses `.spread`.
- Keep CSS inline and images embedded as data URIs or referenced by absolute
  URLs. A local stylesheet or image beside the HTML is not uploaded.
- Draw charts with inline SVG or HTML to keep their shapes editable.
- Use real text and tables. Fonts must be available in the destination app.
- Scripts must settle; avoid observers or resize handlers that retrigger forever.

If the user supplies a finished design, preserve it. If creating one, follow
their brief and use these constraints to make its InDesign export practical.

## Licenses, privacy and errors

Start keyless unless the user already has a license configured. Local licensed
use reads `IDMLY_LICENSE_KEY` from the environment. Use the client's secure
configuration; never put a real key in generated HTML, logs or chat.

Conversion uploads the selected HTML and its included content to the hosted
idmly engine. Files are converted and deleted; remote output waits behind a
one-time download link for up to ten minutes. Only upload files within the
user's requested scope and applicable permissions.

- `402`: explain the trial or license issue and offer the pricing link. Do not
  buy a license, activate extra devices repeatedly or bypass trial limits.
- `413`: the file is too large (15 MB trial, 50 MB licensed). Suggest reducing
  embedded image sizes; preserve the original file.
- `422`: check missing assets, page dimensions or scripts that do not settle.
- `429` / `503`: honor the returned retry delay and avoid repeated submissions.
- Large files may take a few minutes. A client timeout is not proof that the
  conversion failed; do not keep resubmitting the same design blindly.

Setup guide: https://www.idmly.com/mcp-server-indesign.html#connect
Package documentation: https://www.npmjs.com/package/idmly-mcp
Pricing: https://www.idmly.com/#pricing
Support: support@idmly.com