poster-design-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@poster-design-mcp Design an A4 poster for a bakery's weekend sale: 20% off all bread, use our brand green."
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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
Related MCP server: visualspec
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/The design system is numbers, not vibes. Twelve rules were read off four reference posters and written into
src/design-system.jsas 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.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.Headless Chrome does the layout. Rendering in a browser buys real text layout — font fallback, hyphenation,
object-fitcropping,mix-blend-mode: multiplyletterforms — 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 withdeviceScaleFactordoing the work, so a 300 dpi A4 is genuinely 2480×3508 pixels rather than an upscale.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 installnpm install pulls Puppeteer, which normally downloads its own Chrome. If it didn't, or if
you skipped the download:
npx puppeteer browsers install chromeChrome 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 testThat boots the server over stdio, exercises every tool and asserts the token budgets. Then, for something to look at:
npm run demoOne 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.jsClaude 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.
Environment variable | Meaning |
| What relative image and output paths resolve against |
| Moves the default output folder off |
| Explicit Chrome/Chromium binary |
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
\nin 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.
| The same poster with no photo. Drop the |
|
|
|
|
Sample photography is placeholder imagery included for demonstration; swap in your own.
Tools
Tool | What it does |
| The four layouts and when to use each, plus palettes, sizes and fonts. Pass a |
| The twelve rules, type scale and layout ratios. Pass |
| Renders one poster to PNG/JPG and returns the path. Pass |
| The same copy across up to 4 templates or palettes, for comparison |
Templates
id | Based on | Use it for |
| A jazz festival bill | Events, launches, line-ups. Pattern band + photograph + type block + sponsor rail |
| A typographic brand poster | Brand statements and campaign words, when there is no photograph worth printing |
| An insurance campaign ad | Product and service advertising with a call to action and small print |
| An anniversary ad | Milestones, results and offers with a number in them |
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.
| Resolves to |
omitted |
|
|
|
| exactly that — relative forms against |
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_templatesreturns ~390 tokens instead of ~1,700; pass atemplateid for one layout instead of all four.get_design_principlesreturns ~280 tokens instead of ~1,700;detail: truefor 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 budgetssrc/
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 resolutionsaveHtml: 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
Symptom | Fix |
|
|
Tools don't appear in the client | Use an absolute path to |
Images don't render | Local paths resolve against |
Poster written somewhere unexpected | Default is |
Headline overflows | Put your own |
Creator
Built by Suprise Nkosi.
Facebook — facebook.com/suprise.nkosi.524
GitHub — @suprisedr
Issues and pull requests are welcome.
License
MIT — see LICENSE.
Available Tools
4 toolscreate_posterB
Render a business poster to a PNG/JPG in ~/Poster Designs. Auto-fitted display type, band structure, one accent colour, protected legibility. Returns the file path.
Inputs: content (required), template (required), seed, size, +12 more.
create_poster_variantsA
Same message across several templates/palettes in one call, to compare directions.
Inputs: content (required), variants (required), template.
get_design_principlesA
The design rules, type scale and layout ratios the generator applies. For writing copy that fits, or critiquing output.
Inputs: detail, brandColor.
list_poster_templatesA
Field guide for the poster layouts, plus palettes, sizes and fonts. Pass a template id for that one layout only. Call once before create_poster if unsure.
Inputs: template.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 4 tools
Each tool has a clearly distinct purpose: discovering templates, learning design principles, creating a single poster, and creating variants. Even the two create tools are distinguishable by single vs. batch behavior.
All tool names follow the same verb_noun snake_case pattern: list_, get_, create_, create_. The naming is predictable and indicates the action and resource clearly.
Four tools is well-scoped for a poster design server, covering discovery, guidance, creation, and variation. The set feels intentionally minimal rather than bloated or incomplete.
The core workflow is covered: browse templates, learn design rules, create a poster, and generate variants. Minor gaps exist around modifying or deleting generated posters, but these are not clearly required for the server's stated purpose.
Maintenance
Related MCP Connectors
Generate product images, posters, reels, and videos from your photos.
Make ad creatives, social media posts and banners from a brief. Editable designs you can reuse.
Generate branded images at scale: design templates and render them to PNGs by prompt.
Turn any idea, URL, doc, or PDF into on-brand visuals: 100+ formats, native in 150+ languages
Related MCP Servers
AlicenseAqualityCmaintenanceEnables AI agents to generate on-brand visuals from ideas, URLs, documents, or PDFs in over 100 formats and 150+ languages, with consistent brand kits.1628 npm1MIT- AlicenseNot gradedqualityBmaintenanceEnables AI agents to convert natural-language briefs into structured visual specs, deterministically render typography and layouts, and run constraint-aware visual QA and targeted repair for image generation.41 npmApache 2.0
- AlicenseCqualityBmaintenanceEnables AI agents to autonomously create and edit graphic designs, multi-page PDF catalogs, brochures, social media assets, and slide decks on a local browser canvas. It provides vision-in-the-loop feedback, layout audits, and export capabilities for print-ready or web-ready outputs.53104 npmMIT
- AlicenseNot gradedqualityCmaintenanceTurns photos plus a short brief into finished social-media designs such as stories, carousels, reel covers and invites. It searches and ranks templates, uploads images, places photos and copy, and returns rendered designs with links for further editing.Apache 2.0