poster-design-mcp

An MCP server that designs business posters. Ask your AI client for a poster in plain language and it writes a real PNG or JPG to disk — print-resolution, laid out by a design system rather than by guesswork.

Every poster on this page was produced by a single tool call. More in Gallery.

Contents

• What it does

• How it works

• Install

• Connect it to your AI client

• Using it

• Tools

• Templates

• Sizes, palettes and images

• Where posters are saved

• Token cost

• Development

• Troubleshooting

• Creator

• License

Related MCP server: Canvora MCP

What it does

Most AI image tools paint a poster, so the type comes out melted and the phone number is fiction. This one typesets a poster. The headline is real text in a real font, the price is the price you gave it, and the output lands on exact pixel dimensions — 2480×3508 for A4 at 300 dpi, ready for a printer.

You get:

• Four layouts derived from four reference posters — events, brand statements, product ads, and milestone numbers.

• A palette from one hex code. Give it your brand colour; field, ink, accent and pattern ramp are derived from it, with the ink picked by contrast ratio so text stays legible.

• Auto-fitted display type. The headline grows until the longest line touches the margin, then stops. You choose the line breaks; the server chooses the size.

• Real photograph handling — full-bleed crops, focal points, gradient scrims so type never sits raw on an image.

• Print or social sizes, PNG or JPG, on demand.

How it works

  your prompt
      │
      ▼
  AI client  ──MCP/stdio──▶  poster-design-mcp
                                  │
                                  │ 1. pick a template  (src/templates/*.js)
                                  │ 2. derive the palette from brandColor
                                  │ 3. build an HTML + CSS document
                                  ▼
                            headless Chrome  ── screenshot ──▶  poster.png
                                                                     │
                                                                     ▼
                                                        ~/Documents/Poster Designs/

1. The design system is numbers, not vibes. Twelve rules were read off four reference posters and written into src/design-system.js as values the templates actually consume — margin at 6.8% of the width, hero type between 0.055 and 0.155 of the width, leading 0.90, tracking −0.03em. The prose in DESIGN-PRINCIPLES.md and the rendered pixels read from the same constants, so the documentation cannot drift away from the output.

2. A template turns your copy into a document. Each of the four templates (src/templates/) is a function: content in, HTML and CSS out. It places the bands, sets the type roles, generates the decorative pattern from a seed, and inlines every local image as a data URI.

3. Headless Chrome does the layout. Rendering in a browser buys real text layout — font fallback, hyphenation, object-fit cropping, mix-blend-mode: multiply letterforms — and the auto-fit loop measures the actual laid-out headline and rescales until it fills the measure. The page is then screenshotted at the exact output dimensions with deviceScaleFactor doing the work, so a 300 dpi A4 is genuinely 2480×3508 pixels rather than an upscale.

4. The file goes to Documents. An MCP server is launched by its client and has no meaningful working directory, so results are written somewhere findable and the tool returns the path.

Nothing is uploaded. No API key, no network call — the whole pipeline runs on your machine.

Install

Requires Node 20+ and a Chrome/Chromium binary.

git clone https://github.com/suprisedr/poster-design-mcp.git
cd poster-design-mcp
npm install

npm install pulls Puppeteer, which normally downloads its own Chrome. If it didn't, or if you skipped the download:

npx puppeteer browsers install chrome

Chrome is located in this order: $POSTER_CHROME_PATH → Puppeteer's managed Chrome → Google Chrome or Chromium in the usual system locations. To point at a specific binary:

export POSTER_CHROME_PATH="/Applications/Google Chrome.app/Contents/MacOS/Google Chrome"

Check that it works:

npm test

That boots the server over stdio, exercises every tool and asserts the token budgets. Then, for something to look at:

npm run demo

One poster per template into ./examples.

Connect it to your AI client

Claude Code

claude mcp add poster-design -- node /absolute/path/to/poster-design-mcp/src/server.js

Claude Desktop, or any MCP config file

Add to mcpServers (on macOS, Claude Desktop's config lives at ~/Library/Application Support/Claude/claude_desktop_config.json):

{
  "mcpServers": {
    "poster-design": {
      "command": "node",
      "args": ["/absolute/path/to/poster-design-mcp/src/server.js"],
      "env": {
        "POSTER_BASE_DIR": "/absolute/path/to/poster-design-mcp"
      }
    }
  }
}

Use absolute paths — the client launches the server from an unpredictable directory.

Restart the client, and the four tools appear.

Using it

Once connected, you just ask:

Make me an A4 poster for Golden Crust Bakery — handcrafted breads and pastries, 123 Maple Street, open 6am–6pm Tuesday to Sunday. Warm orange, use this bread photo.

The client picks a template and calls create_poster. Under the hood that is one JSON payload:

{
  "template": "photo-overlay",
  "brandColor": "#0F918F",
  "size": "instagram-portrait",
  "format": "jpg",
  "content": {
    "brandName": "Guski",
    "logoBadge": true,
    "headline": "You love it,\nwe cover it",
    "subhead": "Cover that changes everything",
    "cta": { "label": "Get a quote", "phone": "061 306 081" },
    "legal": "Guski Short Term Insurance Ltd. Reg. No. 89/524.",
    "image": "examples/sample-photo.jpg",
    "imageFocus": "50% 45%"
  }
}

It returns one terse line — path | 2480x3508 png | 191KB | ... — and the file is on disk.

Two things worth knowing when you write the copy:

• Use \n in a headline to choose where it breaks. The generator sizes the type to fill whatever rag you write, so the break is a design decision and it's yours.

• Keep it short. Headline 2–5 words, subhead under 45 characters, body two lines. The type scale is built on extreme contrast; long copy is what makes a poster look like a flyer.

Gallery

Real output, one tool call each.

Sample photography is placeholder imagery included for demonstration; swap in your own.

Tools

Templates

The rules behind them are in DESIGN-PRINCIPLES.md — one message per poster, bands not boxes, 6–12× scale contrast, one margin value, end on a pill.

Sizes, palettes and images

Sizes. a4-print (2480×3508 @300dpi), a3-print, a5-flyer, poster-hd, instagram-post, instagram-portrait, story, web-banner — or pass width and height in pixels. Output lands on exactly those dimensions.

Colour. Pass brandColor as a hex and the full palette is derived from it. Or pass palette for one of the named sets (festival-block, prism-glass, night-drive, signal-teal, mono-ink), which wins over brandColor.

Images. image, logo, badge.logo and partners[].logo take a local path (absolute, ~, or relative to POSTER_BASE_DIR) or an http(s) URL. Local files are inlined as data URIs before rendering. For stat-hero, a cut-out subject on a transparent PNG gives you the effect of the subject crossing the numeral.

Where posters are saved

Finished posters go to ~/Documents/Poster Designs.

Set POSTER_OUTPUT_DIR to move the default somewhere else, or outputPath for one exact file.

Token cost

An MCP server's tool list is re-sent on every request of every session, so this one is written to stay cheap to keep in context:

• The tool list is ~990 tokens, down from ~2,600. It carries names, options and field names; field meanings moved behind list_poster_templates, which is called once by the callers that need it.

• list_poster_templates returns ~390 tokens instead of ~1,700; pass a template id for one layout instead of all four.

• get_design_principles returns ~280 tokens instead of ~1,700; detail: true for the full reasoning.

• Results are one terse line rather than pretty JSON.

• The inline preview image (200–500 tokens per poster) is opt-in via preview: true. The file is in Documents, which is a better place to look at it.

npm test asserts the tool-list budget, so a regression in the most expensive surface fails the build.

Development

npm run demo    # one poster per template into ./examples
npm test        # boots the server over stdio, exercises every tool, checks the token budgets

src/
  server.js          MCP wiring: tool list, dispatch, terse results
  poster.js          orchestration — template → HTML → render → write
  design-system.js   the twelve rules as numbers: palettes, type scale, layout ratios
  templates/         one file per layout, each content → { body, css }
  lib/
    html.js          document assembly and escaping
    pattern.js       seeded decorative pattern generation
    media.js         image resolution and data-URI inlining
    render.js        headless Chrome lifecycle and screenshotting
    paths.js         output directory resolution

saveHtml: true writes the HTML source next to the image, which is the fastest way to see why something laid out the way it did. seed makes the pattern and jitter reproducible.

Troubleshooting

Creator

Built by Suprise Nkosi.

• Facebook — facebook.com/suprise.nkosi.524

• GitHub — @suprisedr

Issues and pull requests are welcome.

License

MIT — see LICENSE.