imagormcp

README

imagor-mcp

An MCP server and a skill that add template capability to imagor.

An agent writes a layout; the layout compiles to one imagor URL — pasted in a browser, stored, served from a CDN, put in a page.

Every card above is one imagor URL, composed by an agent from a brief. All fourteen, with the URL each resolves to, and a prompt to ask for it »

Quick start

1. Run an imagor.

docker run --rm -p 8000:8000 shumc/imagor -imagor-unsafe

Leave it running, and use a second terminal for the rest.

Unsafe mode is for trying things out. Production runs on IMAGOR_SECRET — see imagor's security docs.

2. Install the MCP server.

brew trust cshum/tap && brew install imagor-mcp

3. Point a client at it.

your client	what to do
VS Code	add it from here — one click
Claude Desktop	open imagor-mcp.mcpb — one click
Cursor, Claude Code, Windsurf	add the block below to its config file
Codex	the same values in TOML, at ~/.codex/config.toml

{
  "mcpServers": {
    "imagor": {
      "command": "imagor-mcp",
      "env": { "IMAGOR_UNSAFE": "1", "IMAGOR_BASE_URL": "http://localhost:8000" }
    }
  }
}

Those two settings have to match what you started in step 1: IMAGOR_UNSAFE puts this server in the same mode, and IMAGOR_BASE_URL is where imagor is. Everything else it takes is in Configuration.

VS Code keys its servers under servers and Codex reads TOML, so the block above fits neither. Every client's file path, and the shape each one wants, is in docs/clients.md.

4. Ask it for something. Name a recipe from the cookbook — each one carries a prompt to paste — or describe the image you want. The agent composes through the tools: it writes the layout, renders it, looks at the result, and hands you back the url. Neither of you needs imagor's path syntax — the tools build the path, and refuse one that cannot work.

That is the whole install. It is also on the official MCP Registry, where a client can install it by name, and as ghcr.io/cshum/imagor-mcp in a container — which needs a different base URL, in Configuration. Windows binaries are on the releases page.

Before anything is public, read Security — what this server is trusted with, and what it refuses.

What an agent does with it

A brief like this one:

Build a 1200×630 launch card: a deep green ground, a serif headline, a product photo on the right, and the price below it. Show me what it looks like.

It writes the template, renders it, looks at the image, and revises. Given a brief with no layout, no positions and no sizes, an agent designed three distinct banners across three runs — hierarchy, colour, type pairing, invented copy — and zoomed into regions to read the small text it had drawn.

What this adds

The template layer runs inside your imagor. Rendering stays in the instance you run, at the throughput it already has.

A layout compiles to a URL; a hosted template API returns an image. Those bill and transfer the bytes on every render. imagor serves a URL instead, which any browser, proxy or CDN can cache — so the bytes are transferred once.

Tools

Each tool maps onto a concept in the imagor path grammar. The list, and what each is for, is in docs/tools.md.

The cookbook

cookbook/ holds fourteen ready-made layouts — OG cards, a product grid, a profile card, quotes, testimonials, an event, a comparison table, a price ladder. Take the closest, change the values, render it.

Every card, and the path it resolves to » The template is not on that page: a recipe travels in the server and arrives by name.

Every recipe renders at three canvas sizes on every commit, and the contact sheet above is generated by that same job, so both stay current.

Going deeper

The rest of the documentation:

• docs/format.md — a template carries no canvas size, and why a path cannot be read back into a template.
• docs/tools.md — every tool the server serves, and the prompt.
• docs/skill.md — the skill the server carries, and what it covers.
• docs/security.md — what it is trusted with, and what it refuses.
• docs/clients.md — the config file each client reads, and the two that key their servers differently.
• docs/configuration.md — every setting, and what the cache does for previews.
• docs/development.md — building, testing, and the CLI.

Licence

MIT.

Documentation

Overview

Package imagormcp exists to carry the skill into the binary.

The skill is the part of using this server that does not fit in a tool description: the order a path is written in, how overlays and text are placed, and a working method. A client that only reads tools/list never sees it, so it is embedded here and served as a resource, and the server's instructions point at it.

Index

• Variables

Variables

var Cookbook embed.FS

Cookbook is the recipe set. A recipe is the agent's intermediate channel - it is what gets handed to render_template, not what a reader of the cookbook page wants - so the page carries the name and what the card is for, and the template arrives by name.

var CookbookIndex string

var Skill string

The skill travels with the server: a client that reads only the tool list never sees a file, and these carry what a tool description cannot.

var Sources string

Sources is the fixture table. It is separate from the skill because every agent that touches this server reads the skill, while only an agent choosing what to put in an image field wants sixteen rows of names and dimensions.