Nakkas

Nakkas is an MCP (Model Context Protocol) server that lets AI assistants like Claude create animated SVG graphics from a declarative JSON config: logos, icons, loading spinners, GitHub README banners, badges, and generative art. It renders CSS @keyframes and SMIL animations with no JavaScript, so the output works inside GitHub READMEs and anywhere an <img> tag renders SVG. Every render comes back as a PNG preview plus a server-side artifact id, so the AI sees its own work immediately and iterates without the SVG text ever passing through its context window.

nakkaş means painter/artist in Turkish (old).

"make a neon terminal logo with animated binary digits"
  → AI constructs JSON config
  → nakkas renders to animated SVG
  → AI previews the PNG, critiques, revises
  → clean animated SVG output

Why

• One tool, infinite designs. render_svg takes a JSON config. AI fills in everything.
• The AI sees its own work. Every render returns a PNG preview, so the model critiques and revises instead of designing blind.
• Token-cheap iteration. The SVG stays on the server as an artifact; preview and save address it by id, so revision loops don't pay for the SVG text.
• Pure declarative SVG. CSS @keyframes + SMIL animations, no JavaScript. Survives GitHub's camo proxy.
• Zero external deps. No cloud API, no API keys. Runs locally.

Install

Claude Desktop

Add to your config file:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Linux: ~/.config/Claude/claude_desktop_config.json
• Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "nakkas": {
      "command": "npx",
      "args": ["-y", "nakkas@latest"]
    }
  }
}

Claude Code (CLI)

claude mcp add nakkas npx nakkas@latest

Cursor / Zed / Other MCP clients

{
  "mcpServers": {
    "nakkas": {
      "command": "npx",
      "args": ["-y", "nakkas@latest"]
    }
  }
}

Local Development

git clone https://github.com/arikusi/nakkas
cd nakkas
npm install && npm run build
# Use dist/index.js as the command

Quick Start

Ask your AI (with Nakkas connected):

"Make an animated SVG: dark terminal frame (800×200), glowing cyan text 'NAKKAS', neon glow filter, fade-in on load."

"Create a loading spinner: a circle with a draw-on stroke animation that loops every 1.5 seconds."

"Data visualization: animated bar chart, 5 bars, each fading in with a staggered delay, gradient fills."

"Profile badge (400×120): blue-to-purple gradient, white username text, drop shadow, subtle pulse animation."

Tools

Nakkas provides three tools:

The intended workflow: render → look at the returned preview → revise the config → render again → save. The rendered SVG stays on the server as an artifact: render_svg answers with the preview image and an id like art-1, and preview/save accept that id directly. The SVG text never has to travel back through the model's context window, which cuts the token cost of an iteration loop to a fraction of pasting SVG around. Artifacts live for the server process lifetime (capped at 32, oldest evicted).

The save Tool

{ "artifact": "art-1", "outputPath": "./design.svg", "format": "auto" }

Pass either artifact (id from render_svg, preferred) or content (raw string). Formats: auto (infers from extension), svg (text file), png (renders to raster first). If the file exists, a numeric counter is appended to prevent overwriting. The actual saved path is returned.

The render_svg Tool

Input: SVGConfig JSON object Output: PNG preview image + a summary naming the artifact id, plus optional design analysis notes

The response shape is controlled by an optional output block in the config:

{ "output": { "svg": false, "preview": true, "previewWidth": 800, "minify": false } }

• svg: true includes the full SVG text in the response (off by default; the artifact id covers preview and save)
• preview: false skips the PNG image
• previewWidth scales the preview
• minify: true collapses whitespace in the stored and saved SVG
• frames: N (2 to 10) replaces the static preview with one filmstrip image sampling the CSS animations at N points in time — the way to verify motion, since a single preview only shows the starting state

With frames, nakkas evaluates the @keyframes math itself (duration, delay, iteration count, direction, fill mode, easing per segment) and bakes each sampled state into a static frame. Transform origins declared as transform-box: fill-box are resolved numerically from the element's geometry. SMIL animations are not sampled.

After rendering, the response may include design warnings about common issues such as too many concurrent animations, missing transformBox, group-level scale transforms, content extending past the viewport (measured from the real rendered bounding box, with the overflow in pixels), or low-contrast text against the canvas background (WCAG ratios). Text gets its own layout audit: every text element's ink bounding box is measured through an isolated render, so text escaping the viewport is named with its exact overflow, and two texts printed over each other come back as an overlap warning naming both.

SVGConfig Structure

{
  canvas: {
    width: number | string,   // e.g. 800 or "100%"
    height: number | string,
    viewBox?: string,          // "0 0 800 400"
    background?: string        // hex "#111111" or "transparent"
  },

  defs?: {
    gradients?: Gradient[],   // linearGradient | radialGradient
    filters?: Filter[],        // preset or raw primitives
    clipPaths?: ClipPath[],
    masks?: Mask[],
    symbols?: Symbol[],
    paths?: { id, d }[],      // for textPath elements
    patterns?: Pattern[],     // repeating tile fills
    markers?: Marker[]        // arrowheads: triangle | arrow | circle | square | diamond | bar
  },

  elements: Element[],         // shapes, text, groups, use instances

  animations?: CSSAnimation[]  // CSS @keyframes definitions
}

Element Types

Two field names differ from raw SVG on purpose: the string of a text element goes in content (on textPath it is text), and validation errors will point you to the exact field if you mix them up. Pattern groups rotate each copy to face outward by default; set rotateChildren: false when the child is text or any shape that should stay upright.

All Visual Elements (Shared Fields)

{
  id?: string,             // required for filter/gradient/clip references
  cssClass?: string,       // matches CSS animation names
  fill?: string,           // "#rrggbb" | "none" | "url(#gradId)"
  stroke?: string,
  strokeWidth?: number,
  strokeDasharray?: string, // "10 5", use for draw-on animation
  strokeDashoffset?: number,
  opacity?: number,        // 0–1
  filter?: string,         // "url(#filterId)"
  clipPath?: string,       // "url(#clipId)"
  transform?: string,      // "rotate(45)" "translate(100, 50)"
  transformBox?: "fill-box" | "view-box" | "stroke-box",  // set "fill-box" for CSS rotation
  transformOrigin?: string, // "center", works with fill-box
  smilAnimations?: SMILAnimation[]
}

Filter Presets

Reference as filter: "url(#myId)" on any element after defining in defs.filters:

{ "type": "preset", "id": "myGlow", "preset": "glow", "stdDeviation": 8, "color": "#ff00ff" }

…