Gridform MCP server

A Model Context Protocol server that exposes the Gridform poster engine to any MCP client (Claude Desktop, IDEs, agents). It generates, renders, and translates Swiss-style posters headlessly in Node — the same single inline SVG the web app renders, rasterised to PNG with resvg. No browser, no second render path.

Most tools need no API key. The AI tools call Anthropic with a key you provide (per call or via the environment).

New here? Read the full guide — setup, Claude Desktop config, every tool with examples, and troubleshooting.

Use it

With Node 20+ installed, add the server to any stdio MCP client — nothing to clone or build; npx fetches the published package on first run and caches it. For Claude Desktop, add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/):

{
  "mcpServers": {
    "gridform": {
      "command": "npx",
      "args": ["-y", "gridform-mcp"],
      "env": { "ANTHROPIC_API_KEY": "sk-ant-…" }
    }
  }
}

The ANTHROPIC_API_KEY is optional — the engine tools work without it, and the AI tools also accept an apiKey argument per call. Then ask, e.g. "make a poster for a jazz night, 16:9" or "translate it into Spanish and French".

Tools (29)

Discovery (no key): list_layouts · list_looks · list_formats · list_palettes · list_fonts · list_vibes — browse the design vocabulary.

Generate (no key): create_poster (text → poster) · poster_from_text (paste a blob → a finished poster) · generate_layout (synthesize a content-fit layout) · bento_poster (best-of-N bento grid) · resonate (mood-match palette / type / scale).

Vary (no key): shuffle_poster · surprise_poster · explore_variations (a graded shortlist) · morph_posters (blend two designs).

Refine (no key): art_direct (never-worse elevation) · critique_poster (score + located issues) · harmonize_palette (one hex → four roles).

Format (no key): resize_poster (adapt the layout to any format / ratio / custom size).

Output (no key): render_poster (PNG/SVG + transparent crop) · export_pdf (print-ready, DPI + crop / registration marks) · export_jpg · batch_render (many formats in one call).

AI (Anthropic key): compose_poster · design_poster (full design incl. typeface + motion) · write_copy · translate_poster · brief_to_campaign (brief → N on-brand variations) · critique_and_fix (AI tightens the copy, the engine art-directs).

Everything renders the same SVG the web app uses — PNG/JPG via resvg, PDF via the same resvg PNG embedded with pdf-lib. Deterministic by seed.

Resources & prompts

• Resources: JSON catalogs gridform://catalog/{layouts,looks,formats,palettes,fonts,vibes}, a gridform://guide, rendered specimen sheets gridform://specimen/{looks,palettes,fonts}.png, and a templated gridform://specimen/layout/{layoutId}.png (with id autocompletion).
• Prompts: design_brief, critique_request, campaign_plan, localize.

Developing in this repo

cd mcp
npm install
npm run build        # bundles dist/server.mjs (+ dist/smoke.mjs) and syncs fonts/ + LICENSE
npm run smoke        # headless render self-check (writes dist/sample.png)
npm test             # spawns the server and drives it over stdio

Point a client at the local build with "command": "node", "args": ["…/mcp/dist/server.mjs"] instead of the npx config.

Notes

• Same SVG as the app. Rendering reuses serializePosterArt → <PosterArt>; the self-hosted woff2 typefaces ship inside the package (fonts/), embedded as base64 (override the directory with GRIDFORM_FONTS_DIR). PNGs match the web export by construction.
• Bundled typefaces. The fonts/ woff2 files are open-licensed typefaces (OFL / Apache and similar); they remain under their own licences. The package licence covers the server only.
• Latin-script translation. translate_poster targets languages the bundled fonts cover (Spanish, French, German, Portuguese, Italian, …). For CJK / RTL, take the returned copy and set a matching font.
• Determinism. Engine tools are pure: the same inputs + seed always produce the same poster.
• stdout is the JSON-RPC channel; all logs go to stderr.