Affinity Creative MCP

A safe local MCP server for automating Affinity Photo, Designer, and Publisher from Codex or another MCP client.

It presents a modern stdio MCP interface and bridges to Affinity 3's native loopback connector. The public tools use fixed, validated operations; Affinity's unrestricted execute_script capability is deliberately not exposed.

Platform support

What it can automate

App and documents

Layers and editing

Edits return a historyPosition, are undoable, and remain unsaved until affinity_save_document is called. affinity_undo requires that exact position so it refuses to undo if another edit occurred in between.

Guarded text replacement

Text replacement is a preview-then-apply workflow:

1. affinity_find_text returns every literal match plus the document history position, match count, and a fingerprint of the exact text-layer snapshot.

2. Pass those three guards to affinity_replace_text. It rescans and refuses the edit if the document, count, or fingerprint changed.

3. Render a preview. Save only after approval, or use the returned history position with affinity_undo.

affinity_batch_replace_text supports the same pattern for up to 20 already-open documents:

• mode: "dry_run" returns a guarded plan for every session.

• mode: "apply" preflights every plan before changing any document, applies one undoable history operation per document, and guarded-undoes earlier documents if a later replacement fails.

• Batch replacements are deliberately left unsaved. Save each native source explicitly with affinity_save_document, or create new deliverables with affinity_batch_export.

Literal matching supports case-sensitive or case-insensitive search, optional whole-word matching, and an exact layer-name allowlist. It is glyph-aware, so matches after emoji map to the correct Affinity story positions. Dynamic fields and special glyphs form safe search boundaries. Search phrases containing line breaks are rejected in this release.

Affinity preserves formatting outside each replaced range. Inserted characters inherit formatting from the beginning of that range; mixed character-level styles inside the removed text are not reconstructed. Longer replacement text can reflow or overflow a frame, so preview before saving.

This feature operates on real editable Affinity text only. It does not OCR raster images, restore outlined text, edit text inside embedded documents, or modify linked multi-frame text flows.

Preview and export

Curated exports include PNG, four JPEG qualities, GIF, RGB/CMYK TIFF, SVG variants, PDF variants, EPS, editable PSD, and lossy/lossless WebP.

SDK inspection

affinity_list_sdk_documentation and affinity_read_sdk_documentation expose Affinity's installed documentation for diagnostics. They do not expose raw script execution.

One-time Affinity setup

This server was built and live-tested against Affinity 3.2.0 on macOS.

1. Open Affinity.

2. Open Affinity > Settings > Model Context Protocol.

3. Enable Enable Affinity MCP.

4. Enable Access files on your Desktop.

Desktop access is required because Affinity limits SDK file I/O to that location. Image placement and exports use unpredictable Desktop staging names, validate the result, copy it exclusively to an allowed destination, and clean up staging.

Affinity 3.2's SDK cannot reliably close a document. Consequently:

• Every new document is first saved to a random hidden Desktop staging file, then committed to the requested path with an exclusive, hash-verified copy. This preserves the no-overwrite guarantee even if another process races for the destination.

• Call affinity_open_document on the final path before editing it, and close the hidden staging document manually when convenient.

• There is intentionally no affinity_close_document tool.

Install from source

git clone https://github.com/enoyola/affinity-creative-mcp.git
cd affinity-creative-mcp
npm ci
npm run check

Requirements: macOS, Affinity 3 with its MCP connector enabled, and Node.js 22.7.5 or newer.

The automated suite covers schemas, fixed-script generation, hostile-string escaping, text history/fingerprint guards, timeout audits, verified batch rollback, path and symlink containment, no-overwrite behavior, bridge reconnect behavior, staging policy, and MCP protocol discovery. Glyph-aware matching after emoji, partial range replacement, formatting inheritance, exact undo, placement, effects, save, PNG export, and rendering have also been live-validated against Affinity 3.2.

Codex configuration

From the cloned repository, register the built server with Codex:

NODE_BIN="$(command -v node)"
SERVER_ENTRY="$(pwd)/dist/index.js"

codex mcp add affinity-creative \
  --env "AFFINITY_MCP_ALLOWED_ROOTS=$HOME/Documents:$HOME/Desktop" \
  -- "$NODE_BIN" "$SERVER_ENTRY"

A TOML form is in codex-config.example.toml. Replace its placeholders with the output of command -v node, the absolute path to dist/index.js, and your desired allowed roots. Restart Codex after adding the server or rebuilding its tool surface so a new MCP process loads the updated tools.

For another MCP client, configure a local stdio server whose command is your Node.js executable, whose first argument is the absolute path to dist/index.js, and whose environment includes AFFINITY_MCP_ALLOWED_ROOTS.

Example requests

Create a 1920 × 1080 px Designer document on my Desktop, add a purple
background rectangle and a white headline saying "Summer launch", then save it.

Open /Users/YOUR_USERNAME/Documents/Creative/post.af, list its layers, select the layer
named Product, move it 40 px right, add a 2 px Gaussian blur, and show me a preview.
Do not save until I approve the preview.

Place /Users/YOUR_USERNAME/Documents/Assets/logo.png at x 120, y 80 in the open document,
resize it to 360 px wide, export the whole document as high-quality JPEG, and also
export a PDF for print. Do not overwrite existing files.

In these ten open Affinity documents, find every editable occurrence of "XYZ".
Show me the dry-run counts first. If every document is ready, replace them with
"ABC" as unsaved edits, render the first result, and do not save until I approve.

In the open document, replace the whole word "Draft" with "Approved" only in
layers named Header or Footer. Match case, show me a preview, then save it.

Create an 8-page A4 Publisher document in millimetres with facing pages at
/Users/YOUR_USERNAME/Documents/Creative/brochure.af.

For editing calls, Codex obtains documentSessionUuid from document creation, opening, or affinity_list_open_documents. Tools that operate on the current selection can be preceded by affinity_select_layer.

Document creation options

• Workspaces: photo, designer, publisher

• Units: px, mm, cm, in

• DPI and transparent background

• Raster formats: RGBA8, RGBA16, RGBAUF, IA8, IA16, CMYKA8, LABA16

• Designer artboards

• Publisher page count and facing pages

• Native Affinity 3 .af output

The destination directory must already exist. Pixel dimensions must be whole numbers.

Safety model

• Input and output paths must be absolute, canonical, and inside AFFINITY_MCP_ALLOWED_ROOTS.

• Existing output files are never overwritten; final commits use exclusive copies.

• Input files must exist as regular readable files; in-place saves must also be writable native Affinity files.

• Canonical paths are checked so symlink traversal cannot escape an allowed root.

• Image size, text length, coordinates, dimensions, transforms, effects, page counts, DPI, and batch size have explicit ceilings.

• Text replacement uses literal matching, glyph-boundary mapping, exact history/count/fingerprint guards, one compound undo step per document, complete post-edit text readback, and a 5,000-match batch ceiling.

• A text scan is limited to 10,000 layers and 500,000 story glyphs. Insertions are limited to 2,000,000 UTF-16 code units per document and 5,000,000 per batch.

• Batch text apply preflights every open session before editing and never saves source documents implicitly.

• Export format and filename extension must match a curated preset.

• Batch exports preflight every destination, stage every result first, and roll back outputs created by a failed commit.

• Native calls time out and reconnect rather than blocking the script queue forever.

• The Affinity endpoint must remain loopback HTTP. The bridge handles IPv4 and IPv6 localhost listeners.

• User strings are JSON encoded into fixed SDK templates. Raw scripts, shell commands, and network access are not MCP tools.

Environment variables

On macOS, multiple allowed roots are separated by :.

Troubleshooting

• AFFINITY_CONNECTOR_DISABLED: enable both Affinity MCP settings, then call affinity_status again.

• PATH_OUTSIDE_ALLOWED_ROOTS: use a path beneath an allowed folder or deliberately update the server configuration.

• PARENT_DIRECTORY_MISSING: create the destination directory first.

• OUTPUT_EXISTS: choose a new filename; overwrite is intentionally refused.

• INVALID_EXTENSION: make the output extension match the selected export preset.

• DOCUMENT_REQUIRES_SAVE_AS: open or create a native .af document first; automated Save As is intentionally omitted because Affinity cannot close the staged backing document.

• BATCH_TEXT_PREFLIGHT_FAILED: rerun text dry-run because a document, match count, fingerprint, or editability state changed.

• BATCH_TEXT_REPLACE_ROLLED_BACK: a later batch edit failed and earlier content was restored; Affinity may still mark those documents as needing save.

• BATCH_TEXT_ROLLBACK_INCOMPLETE: an external edit changed history, so the MCP refused to risk undoing the wrong operation.

• TEXT_REPLACE_NOT_APPLIED: Affinity lost its response, but a follow-up audit verified the original plan unchanged; rerun find before retrying.

• TEXT_REPLACE_STATE_UNCERTAIN: Affinity lost its response and exact state could not be verified; inspect the document before retrying or undoing.

• AFFINITY_CALL_TIMEOUT: Affinity did not finish in the configured period; the next operation reconnects.

• If rebuilt tools do not appear, restart Codex so it launches the rebuilt MCP process.

Contributing and security

Contributions are welcome. See CONTRIBUTING.md for the development workflow. Please report security issues privately according to SECURITY.md, not in a public issue.

License

Released under the MIT License.