imagormcp

README

Imagor MCP

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

An agent writes a layout: OG cards, product grids, quotes, testimonials. It compiles to one imagor URL, rendered by the imagor you already run.

See the recipes »

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.

VS Code keys its servers under servers and Codex reads TOML, so the block above fits neither. Every client's config file is in Setup.

4. Ask it for something. See the recipes — 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 in the official MCP Registry as io.github.cshum/imagor-mcp, which some clients install by name, and as ghcr.io/cshum/imagor-mcp in a container, which needs a different base URL, in Setup. Windows binaries are on the releases page.

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

Going deeper

• Setup — every setting, the config file each client reads, and what to do before it is public.
• Reference — every tool the server serves, the layout format, and the skill.
• Cookbook — the ready-made layouts, and the url each one resolves to.
• Contributing — 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.