keyline-mcp

keyline.dev: examples, the benchmark, and setup for every client.

Design engine for AI agents: Canva for your agent. keyline is a free MCP server for Claude Code, Claude Desktop, Cursor, Codex, Gemini CLI and any MCP client. Your agent describes a social post, ad or banner once, as a small JSON scene; keyline renders it as images and video at every size, with real text in your fonts and colors, the same every run.

No browser, and fewer tokens. No headless Chrome, Puppeteer or Playwright: one native Rust binary on Skia. Every edit replies with what's wrong at each size, so the agent fixes the design from measurements instead of screenshots: 2× fewer tokens than an agent driving headless Chrome, and 6× fewer than Playwright MCP (benchmark).

One prompt, five sizes: the layout adapts from a 4:5 post to a 728×90 leaderboard, and keyline's checks catch what doesn't fit before anything renders.

More campaigns, with motion, on keyline.dev. Every image there, and the one above, was made with keyline.

---

Why

Most designs people ship today (sale posts, event flyers, ad sets) are made in tools like Canva or Adobe Express. Those tools are built for a person with a mouse, and none is a good backend for an agent:

• Canva and Adobe Express keep their scene graph private: you can export pixels, not the design.
• Browser-based renderers such as Polotno need headless Chrome on the server.

keyline-mcp is the missing piece: an agent-first design tool, with a design format and renderer built from the ground up for a language model to author, check and export, cheaply and reproducibly. The design stays structured data (a typed layer tree with layout, tokens, styles and components), not pixels, so an agent edits it precisely instead of regenerating an image.

How it works

flowchart LR
    A[Agent] -- "layer_add / layer_update" --> S[(Scene JSON)]
    S --> L["Layout per size<br/>scale → constraints"]
    L --> C["Checks<br/>defects · advisories · facts"]
    C -- "ok, or what to fix" --> A
    L --> R["Skia renderer<br/>GPU, CPU fallback"]
    R --> P["PNG, JPEG, WebP, PDF, animated PNG, GIF, MP4 or WebM per size"]

Loading

1. One master layout. A design is written once at a master size and lists its target sizes.
2. Layouts that adapt. Rows, columns, grids and design-tool constraints lay the design out again at every size, with no constraint solver; any layer can change for one size or aspect class.
3. Checks, not previews. Every edit's reply says what's wrong at each size, with the measurement that fixes it.
4. GPU by default, deterministic when it matters. Renders run on the GPU and fall back to the CPU, whose output is exactly repeatable.

Start here: docs/concepts.md explains the model; docs/scene.md is the scene format and docs/tools.md the tools and configuration.

LLM-first, and LLM-only

There's no GUI, and no plan for one. Every design decision is judged by one question: how many tokens does the agent spend to get a correct image? We measure that with a real model (Claude, through Claude Code) building a real multi-section ad.

• Few, batched tools: six tools, not one per property; one call can build a whole ad.
• Short replies: edits return the changed ids, a version, and ok or the problems, never the scene.
• Defaults left out: a typical layer is 4–6 fields.
• Standard names: CSS names and values wherever CSS has the concept (flexbox and grid fields on frames, fontWeight, borderRadius, rgba() colors), so the model writes a scene right the first time. The layout itself is keyline's own, documented, not browser-exact.
• Semantic targets: layers are addressed by role, so the agent never reads the scene to find an id.
• Verification without pixels: defects to fix, advisories to judge and facts to weigh, each with the measurement that fixes it (how).
• Names, not inventions: icons, shapes, styles, tokens and components by name. Icons alone took rebuilding a real flyer from $0.22–0.62 to $0.15–0.19 per run.
• Measured, not guessed: every change is judged on several real-model runs, kept in keyline-bench.
• Taste stays with the model: the server flags only objective defects and reports the rest as facts.

Features

• Layers: text, image (PNG, JPEG, SVG), video, icon, rect, ellipse (and arcs and rings), polygon (and stars), path (SVG path data or a named shape), line, frame (nesting, clipping, stacks, grids), spacer, firstFit, and use for components
• Layout: stacks (CSS flexbox: rows and columns with gap, padding, alignment, justification and wrapping; fill, flexGrow and priorities), grids (CSS grid: tracks, named areas, spans), hug/fill/percentage sizes with min/max and aspect ratio, direction lists and firstFit that pick what fits, constraints, placement at nine spots, a scale factor per size, per-size and per-aspect changes (media), size presets for common social and ad formats, and safe areas a platform covers
• Text: fit, wrap or one line; inline markup (<b>, <i>, <span style=…>, style names as tags); weights, italics, letter spacing, line height, case; balanced or pretty wrapping; highlights behind words; underline and strike; text on a curve; dot leaders; text filled with an image, pattern or gradient; outlines; text that knocks out its frame. Fonts work like CSS web fonts: name any Google Fonts family and the server downloads it on first use and caches it (tracked in fonts/index.json); Inter is bundled, and you can add your own font files
• Paint: stacked fills (solid, linear/radial/conic gradients, images, patterns, film grain), strokes (inside, center or outside, per side, dashed, with arrowheads, hand-drawn), shadows (outer and inner, following a cutout's or text's shape), blur and backdrop blur, masks (gradient, shape, path, another layer or an image), torn edges, 16 blend modes, corner radius, rotation, skew, flips
• Images: fill, fit, crop or tile, with a focus point that stays in view; adjustments (brightness, contrast, saturation, grayscale, sepia, hue, duotone, tint, halftone)
• Icons: about 5,000 built in, by name: Lucide outline icons and Font Awesome Free solid, regular and brand icons, in any color
• Reuse: named styles on any layer, tokens ({{brand}}, in any field or sentence) that update every field using them, components placed once or once per data row, and templates: a scene file loaded by URL or path with its variables set, rendered once per row of values
• Motion: GSAP-style animation: enter and exit effects (fade, fade-up, pop, zoom, blur-in), keyframes on opacity, scale, rotation, offset, skew, blur and color with GSAP's eases, random() starts, staggered children, text split into letters or words that move on their own, strokes that draw themselves, and numbers that count
• Video: video clips as layers, trimmed, slowed or looped, with titles and graphics over them; shots that play in turn, joined by cuts, fades, slides, pushes, wipes or zooms; each clip's own sound carried into the video, mixed with a soundtrack
• Assets: stored under content hashes. URLs are fetched only over http(s), and private and local addresses are refused.
• Output: PNG, JPEG, WebP, vector PDF, animated PNG, animated GIF, MP4 or WebM per size, a still of any moment, with a file-size cap for ad networks, plus an optional contact-sheet preview; rendered on the GPU when available

Quick start

Claude Code (macOS or Linux): the plugin downloads keyline and checks it against the release's SHA256SUMS, or uses keyline-mcp from your PATH.

/plugin marketplace add keyline-dev/keyline
/plugin install keyline@keyline

Claude Desktop (Mac with Apple silicon, or Windows): download keyline-mcp-<version>.mcpb from the latest release and double-click it. Designs and their renders go in ~/keyline, a folder per design, where you can also put the images and logos Claude should use. To work in folders of your own instead, open Settings → Extensions → keyline → Configure, add them, and click Save.

Other clients: install, then add

	Install
macOS (Apple silicon)	brew install keyline-dev/tap/keyline-mcp
Linux (amd64, arm64)	sudo apt install ./keyline-mcp_<version>-1_amd64.deb (or _arm64), from the latest release; tarballs are there too
Windows (x64)	Unpack keyline-mcp-v<version>-windows-amd64.zip and put its folder on your PATH
Docker	Use docker run -i --rm -v keyline:/data ghcr.io/keyline-dev/keyline-mcp as the client's command; the :stills tag leaves out ffmpeg
From source	cargo build --release (Rust stable; on Linux also libfontconfig1-dev libfreetype6-dev)

Every release has a SHA256SUMS file and build attestations: gh attestation verify <file> --repo keyline-dev/keyline. Then add keyline to your client. The command is keyline-mcp; if the client can't find it, give its full path (which keyline-mcp).

Cursor

Add to Cursor, or add this to ~/.cursor/mcp.json:

{ "mcpServers": { "keyline": { "command": "keyline-mcp" } } }

VS Code

code --add-mcp '{"name":"keyline","command":"keyline-mcp"}'

Codex (OpenAI)

codex mcp add keyline -- keyline-mcp

Gemini CLI (Google)

gemini mcp add --scope user keyline keyline-mcp

Other clients

Most clients take this JSON, in the file below; links go to each client's guide.

{ "mcpServers": { "keyline": { "command": "keyline-mcp" } } }

Client	Where
Claude Code, without the plugin (and on Windows)	claude mcp add --scope user keyline -- keyline-mcp
Claude Desktop, without the .mcpb	Settings → Developer → Edit Config, with the full path (/opt/homebrew/bin/keyline-mcp); it doesn't read your shell's PATH
Devin Desktop (Windsurf)	~/.config/devin/mcp_config.json; still named Windsurf: ~/.codeium/windsurf/mcp_config.json
Cline	MCP Servers panel → cline_mcp_settings.json
Antigravity	~/.gemini/config/mcp_config.json
Kiro	~/.kiro/settings/mcp.json
JetBrains AI Assistant, Junie	Settings → Tools → AI Assistant → MCP → Add; Junie: ~/.junie/mcp/mcp.json
GitHub Copilot CLI	/mcp add in Copilot CLI
Grok Build	grok mcp add keyline -- keyline-mcp
opencode	opencode.json: "mcp": { "keyline": { "type": "local", "command": ["keyline-mcp"] } }
Warp	Settings → Agents → MCP servers → Add: { "keyline": { "command": "keyline-mcp" } }

Any client that starts stdio servers works. ChatGPT, grok.com and the xAI API connect only to remote servers, so they can't start keyline, which runs on your machine.

Then

Ask your agent for a design: "Make a vote-by-mail flyer with this photo, in 1080×1350, 1200×1000 and a 300×600 skyscraper."

• Your files: each design gets a folder, ~/keyline/<name>/, holding its scene and renders/; the agent adds images, video and templates in it by path (cheaper than sending their bytes) and picks up a design by name in a later session. The Claude Code plugin uses the project folder instead. Elsewhere, --folder ~/work ~/brand replaces ~/keyline: designs go in the first folder, and files are read in all of them. Flags go after the command (claude mcp add keyline -- keyline-mcp --folder ~/work), or in args in a JSON config. In Docker, designs are in the /data volume; mount other folders and pass them.
• Video needs ffmpeg on the PATH; everything else, animated PNG and GIF included, works without it.
• Options: every setting is a flag (--folder, --no-motion, --data, --fonts, --renderer, --ffmpeg, --encoder); see keyline-mcp --help and docs/tools.md.
• Without an agent: keyline-mcp render scene.json --out renders/ renders every size and exits 1 on a ! defect; in GitHub Actions, uses: keyline-dev/keyline@v0 does it for a repo's scenes (details).
• GPU on a Linux server needs Vulkan drivers (NVIDIA's, or Mesa); without a GPU, keyline renders on the CPU.

The tools

Every input and reply format is in docs/tools.md.

Tool	Does	Replies
scene_create	New scene: master size, target sizes, background; or from a template file by URL or path, with its variables set	s5b0a42a5e v0
asset_add	Adds an image or video clip from a URL, a local path or base64	photo 1600×900 v1
layer_add	Adds layers, optionally into a parent frame, and shared styles, tokens and components	added headline,cta v2 ok and facts
layer_update	Changes (set), deletes or detaches layers, styles and components; changes tokens	changed … v3, then problems or ok
scene_describe	Problems per size, or ok; full lists every layer's box	text
render	PNG, JPEG, WebP, PDF, animated PNG, GIF, MP4 or WebM for all or some sizes, or a still at time; rows renders one variant per row of variables; maxKB caps file size; preview adds a contact sheet	paths and how text was drawn

A typical call:

{
  "sceneId": "s5b0a42a5e",
  "layers": [
    {
      "id": "headline",
      "type": "text",
      "x": 60,
      "y": 40,
      "width": 960,
      "fontSize": 64,
      "fontWeight": 800,
      "textAlign": "center",
      "color": "#1B2A5C",
      "text": "Proven <span style=\"color:#D0202E\">RESULTS</span> for WILLOWMERE Families",
      "constraints": {
        "horizontal": "stretch",
        "vertical": "top"
      }
    },
    {
      "type": "image",
      "asset": "photo",
      "y": 220,
      "width": 1080,
      "height": 460,
      "constraints": {
        "horizontal": "stretch",
        "vertical": "stretch"
      }
    },
    {
      "id": "cta",
      "type": "frame",
      "y": 830,
      "width": 1080,
      "height": 100,
      "fill": "#D0202E",
      "constraints": {
        "horizontal": "stretch",
        "vertical": "bottom"
      },
      "children": [
        {
          "id": "cta-text",
          "type": "text",
          "text": "VOTE BY MAIL",
          "x": 394,
          "y": 21,
          "fontSize": 48,
          "fontWeight": 800,
          "color": "#FFFFFF",
          "constraints": {
            "horizontal": "center",
            "vertical": "center"
          }
        }
      ]
    }
  ]
}

and its reply, for the sizes the tests use (1080×1350 at full scale, 1200×1000 at 0.85, a 300×600 skyscraper at 0.28):

added headline,image1,cta v2 ok
smallest text: portrait 48px (cta-text), wide 41px (cta-text), sky 13px (cta-text)

Development

cargo test                                         # unit and end-to-end tests
UPDATE_GOLDEN=1 cargo test --test e2e              # regenerate reference PNGs (deliberately; also e2e_features, e2e_paint, …)
cargo test --test llm_e2e -- --ignored --nocapture # a real model builds an ad; prints cost
cargo test -- --ignored web_fonts google_fonts     # web fonts download once and stay cached (network)
KEYLINE_MCP_BENCH=<label> cargo test --test llm_e2e -- --ignored --nocapture       # keep the run in ../keyline-bench/reference-ad/
KEYLINE_MCP_BENCH=<label> cargo test --test recreate_e2e -- --ignored --nocapture  # rebuild a local design from its image, scored

• Unit tests cover layout, text fitting, rendering down to pixel checks, storage, URL safety and edits.
• Layout tests check every layer's position and size after layout, without rendering.
• End-to-end tests run the real server over stdio, build designs in several sizes, and compare the PNGs with reference images. The images are kept per OS, since glyph rasterization differs by platform, and compared with a small tolerance, since glyph edges also differ slightly between OS versions.
• The LLM tests run Claude Code headless, so they use a Claude subscription and need no API key. They check that no defects remain and report tool calls, tokens and API-equivalent cost. With KEYLINE_MCP_BENCH they keep each run for comparison: the reference ad in keyline-bench (checked out beside this repo, or at KEYLINE_BENCH), and a design rebuilt from its image (kept in the gitignored bench/recreate/local/, since references are often real people's material), scored by how close it looks.
• Releases: pushing a v* tag builds the Linux .deb and tarball (amd64 and arm64) and attaches them to a GitHub release.

Contributions follow CLAUDE.md: Rust only, cargo fmt and clippy -D warnings must pass, changes are reviewed against the rust-skills rules, new dependencies need approval and must be permissively licensed, and every feature comes with unit and end-to-end tests.

License

Functional Source License 1.1, Apache 2.0 future license (FSL-1.1-ALv2): free to use, modify and redistribute, commercially too, for any purpose except a competing use: making keyline available to others in a commercial product or service that substitutes for it or offers substantially the same functionality, which includes offering it as a hosted service. Your own internal use, research, education and work for clients are all allowed. Two years after each release, that release is also available under the Apache License 2.0. For a license to compete, contact the author.

Contributions are welcome under the contributor agreement: contributors assign the copyright in their changes to the author.

Third-party parts keep their own licenses: Skia (BSD-3-Clause) through the skia-safe bindings (MIT), resvg (Apache-2.0 or MIT), rmcp (Apache-2.0), csscolorparser (MIT or Apache-2.0), Inter (SIL OFL 1.1), Lucide icons (ISC) and Font Awesome Free icons by Fonticons, Inc. (CC BY 4.0).