nakkas
nakkas is an MCP server that turns AI into an SVG artist, enabling you to generate, preview, and save animated SVG graphics through a declarative JSON-based configuration. It runs fully locally with no external dependencies, API keys, or cloud services required.
Render SVGs (
render_svg): Generate complete, animated SVG XML from a JSON config — AI controls all design parameters including shapes, colors, gradients, filters, and animations.Supports a rich set of element types:
rect,circle,ellipse,line,polyline,polygon,path,image,text,textPath,group,use, and pattern groups (radial-group,arc-group,grid-group,scatter-group,path-group)Create parametric mathematical curves: rose, heart, lissajous, spiral, star, superformula, hypotrochoid, wave
Define reusable
defs: linear/radial gradients (with animated stops), filter presets (glow, neon, blur, drop-shadow, glitch, chromatic-aberration, noise, outline, inner-shadow, emboss), clip paths, masks, symbols, and tile patternsAnimate with CSS @keyframes (linked via
cssClass) and SMIL animations (animate,animateTransform,animateMotion) — pure declarative SVG, no JavaScriptReceive design analysis warnings about common issues after rendering
Preview SVGs (
preview): Render an SVG string to a PNG image (returned as base64) for visual inspection, with optional width scaling. Renders a static snapshot (t=0). Supports an iterative render → preview → critique → revise workflow (at least 3 iterations recommended).Save to disk (
save): Save the final design as an SVG text file or a PNG raster image. Auto-detects format from file extension, supports explicit format specification, allows custom width for raster output, and auto-increments filenames to prevent overwrites.
Enables the creation of animated SVG assets specifically optimized for display in GitHub README files and other markdown environments.
Turns the AI into a vector artist capable of rendering complex, animated SVG graphics including shapes, path morphing, and advanced filter presets from declarative configurations.
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 outputWhy
One tool, infinite designs.
render_svgtakes 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.
Related MCP server: inkscape_mcp
Install
Claude Desktop
Add to your config file:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonLinux:
~/.config/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"nakkas": {
"command": "npx",
"args": ["-y", "nakkas@latest"]
}
}
}Claude Code (CLI)
claude mcp add nakkas npx nakkas@latestCursor / 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 commandQuick 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:
Tool | Purpose |
| Takes SVGConfig JSON, returns a PNG preview + artifact id (+ design analysis warnings) |
| Re-renders a stored artifact (or raw SVG) to PNG at any width |
| Saves a stored artifact (or raw content) to disk as SVG (text) or PNG (raster) |
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: trueincludes the full SVG text in the response (off by default; the artifact id covers preview and save)preview: falseskips the PNG imagepreviewWidthscales the previewminify: truecollapses whitespace in the stored and saved SVGframes: 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
Type | Required fields | Notes |
|
|
|
|
|
|
|
| Independent horizontal/vertical radii |
|
|
|
|
| Open path: |
|
| Auto-closed shape |
|
| Full SVG path commands |
|
| URL or |
|
| String or |
|
| Text following a curve; path defined in |
|
| Shared attrs applied to all children (no nested groups) |
|
| Instance a symbol or clone an element by |
|
| Place N copies around a full circle |
|
| Place N copies along a circular arc |
|
| Place copies in an M by N grid |
|
| Scatter N copies at seeded random positions |
|
| Distribute N copies evenly along a polyline |
|
| Mathematical curve: |
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" }Preset | Key params | Effect |
|
| Soft halo |
|
| Intense bright glow |
|
| Gaussian blur |
|
| Drop shadow |
|
| Turbulence displacement (animated) |
|
| Desaturate |
| — | Warm sepia tone |
| — | Invert colors |
|
| Boost/reduce saturation |
|
| Shift hues |
|
| RGB channel split for lens distortion look |
|
| Film grain and texture overlay |
|
| Colored outline around the element |
|
| Shadow inside the element |
|
| 3D relief shading effect |
CSS Animations
{
"animations": [{
"name": "pulse",
"duration": "2s",
"iterationCount": "infinite",
"direction": "alternate",
"keyframes": [
{ "offset": "from", "properties": { "opacity": "0.3", "transform": "scale(0.9)" } },
{ "offset": "to", "properties": { "opacity": "1", "transform": "scale(1.1)" } }
]
}],
"elements": [{
"type": "circle",
"cx": 100, "cy": 100, "r": 40,
"cssClass": "pulse",
"transformBox": "fill-box",
"transformOrigin": "center"
}]
}CSS property keys: camelCase (strokeDashoffset) or kebab-case (stroke-dashoffset). Both work.
Animatable CSS properties: opacity, fill, stroke, transform, filter, clip-path, stroke-dasharray, stroke-dashoffset, font-size, letter-spacing and more.
SMIL Animations
Three SMIL types, defined inline on each element via smilAnimations: []:
{ "kind": "animate", "attributeName": "d", "from": "...", "to": "...", "dur": "2s" }
{ "kind": "animateTransform", "type": "rotate", "from": "0 100 100", "to": "360 100 100", "dur": "3s" }
{ "kind": "animateMotion", "path": "M 0 0 C ...", "dur": "4s", "rotate": "auto" }Path morphing (attributeName: "d"): from/to paths must have identical command types and counts. Only coordinates can differ.
Fonts
Prefer the CSS generic families: sans-serif, serif, monospace. They resolve to a real font on every platform, both in browsers and in nakkas previews. Named fonts like Arial or Helvetica only exist on some systems (not on most Linux machines), so a design that depends on them will render differently elsewhere. The safe pattern is a named font with a generic fallback: "Georgia, serif".
In preview and PNG save, generic families are resolved through the operating system's own font mapping (fontconfig on Linux), so what the AI sees matches what a browser on that machine would show. Custom font families are accepted and work when the font is available in the rendering environment.
Use Cases & Compatibility
Context | CSS @keyframes | SMIL | External fonts | Interactive (onclick) |
GitHub README | ✅ | ✅ | ❌ | ❌ |
Web page | ✅ | ✅ | ❌ | ❌ |
Web page inline SVG | ✅ | ✅ | ✅ | ✅ |
Design tool export | ✅ | ✅ | ✅ | — |
Static file viewer | ✅ | ✅ | depends | depends |
Troubleshooting
"MCP error -32602: Input validation error"
This means the MCP SDK rejected the input before it reached the handler. It usually happens on the first attempt and works on retry. The most common triggers:
Gradient type typo. Use
"linearGradient"or"radialGradient", not"linear"or"radial". This is the single most frequent mistake.Keyframe offset as string. Write
0or100(numbers) or"from"/"to". Writing"0%"or"100%"will fail.Colors in gradients and filters. Gradient stop and filter colors must be hex:
"#ff0000", not"red"orrgb(). Elementfill/strokeaccept any paint string ("#ff0000","none","url(#id)"), with hex being the safest choice across renderers.Missing
typeon elements. Every element object needs atypefield.
Validation errors that reach the handler name the exact failing field (for example elements.1.content: Required) and append a field reference for the failing element type, so a retry usually succeeds on the first correction. Numeric strings on number fields (letterSpacing: "6") are coerced automatically instead of failing.
The handler also checks reference integrity before rendering: a dangling url(#id) in fill/stroke/filter/clipPath/mask, a use.href pointing nowhere, a textPath.pathId missing from defs.paths, or a duplicate ID all come back as errors with the exact field path and the list of defined IDs, instead of rendering silently broken output.
If you're building an MCP client integration and seeing this consistently, the issue is likely in how your client serializes arguments. See anthropics/claude-code#29104 for context on known serialization quirks.
Preview shows a blank or unexpected image
A single preview renders a static snapshot at t=0, before any animation starts. To see the motion, render with output: { frames: 4 } (or up to 10): nakkas samples the CSS animations at N points in time and returns one labeled filmstrip image. SMIL animations are the exception; they are not sampled and always show their base state.
If the image is completely blank:
Check that your elements have
fillorstrokeset. A shape without fill on a transparent canvas is invisible.Check coordinates. An element at
x: 2000on an800pxwide canvas is simply off-screen.If using
filter: "url(#myFilter)", make suremyFilteris actually defined indefs.filters.
Animations not working on GitHub
GitHub READMEs render SVG through <img> tags, which strips JavaScript but keeps CSS and SMIL. If your animation works locally but not on GitHub:
Avoid
<script>or event handlers (onclick,onmouseover). These are removed.External fonts won't load. Stick to generic families (
monospace,sans-serif,serif) or named fonts with a generic fallback.CSS
@importfor fonts is blocked. If you need a specific font, use inline<text>with a system fallback.
Large SVG output
If render_svg returns a warning about file size (over 50kb), the parametric curves are probably sampling too many points; reduce steps. Pattern groups are cheap: the child is defined once and instanced with <use>, so a grid-group with cols: 50, rows: 50 costs one child definition plus 2500 one-line <use> tags. For the smallest possible file, add output: { minify: true }.
How It's Tested
Every release ships only after a dogfood run: a design produced through the real MCP stdio layer against the freshly built server, iterated render → preview → critique → revise until it holds up. The test design is tailored to the change under test, so the run proves the new feature works under realistic use, not just that nothing broke. The full log, with prompts, iteration counts and the resulting assets, lives in dogfooding.md.
This ritual catches real bugs. The v0.3.0 easing dogfood found that CSS axis shorthands like translateX were baked verbatim into the SVG transform attribute, where they are invalid and silently freeze the element; the fix shipped in the same release. The animation frame sampler behind output.frames is verified against a real browser: randomized animations (seeded, including random cubic-bezier curves) are frozen in headless Chromium via the negative animation-delay trick and must match nakkas's sampled positions within a pixel. That cross-check runs in CI as tests/browser-truth.test.ts; the original manual harness remains at scripts/easing-browser-truth.sh.
Alongside the dogfood runs there are 397 unit and integration tests, including MCP stdio end-to-end coverage.
Tech Stack
TypeScript + Node.js 18+
@modelcontextprotocol/sdk(MCP server)zod(schema validation and AI type guidance)No external SVG libraries, pure XML construction
Vitest (397 tests)
License
MIT. Built by arikusi.
Available Tools
3 toolspreviewPreview SVGA
Render SVG content to a PNG image so the AI can visually inspect the output.
When to use:
render_svg already returns a preview image by default; call this tool to re-preview a stored artifact at a different width, or to preview SVG that did not come from render_svg
Stop iterating when the visual result matches the intent
Input: pass EITHER artifact (id from render_svg, e.g. "art-1" — preferred, no SVG resend) OR content (raw SVG string).
Behavior:
Returns a PNG image (base64) rendered from the SVG
Background is transparent by default
CSS animations and SMIL are rendered as a static snapshot (t=0) — motion is not captured
Width:
Omit width to use the SVG's own declared width/viewBox
Pass width to scale the output (useful for small SVGs that need a larger preview)
Inputs: width, format, content, artifact.
render_svgRender SVGA
Render animated SVG from JSON config. AI controls all design parameters.
Workflow: render_svg returns a PNG preview of the result plus an artifact id — critique the image, revise the config, render again. Iterate at least 3 times before finalizing. The SVG text stays on the server: pass the artifact id to save (and to preview for a different width). Add output:{svg:true} only if you actually need the SVG text in the conversation.
output options (response shape, not content): {"svg":false,"preview":true,"previewWidth":800,"minify":false,"frames":4} — all optional. minify:true collapses whitespace in the stored/saved SVG. frames:N (2-10) replaces the static preview with one filmstrip image sampling the CSS animations at N times — use it to verify motion (rotation direction, timing, easing) since a single preview only shows t=0. SMIL is not sampled.
Element types: rect, circle, ellipse, line, polyline, polygon, path, image, text, textPath, group, use, radial-group, arc-group, grid-group, scatter-group, path-group, parametric
Pattern groups (use for repetitive designs): radial-group (circular: cx, cy, radius, count), arc-group (arc: cx, cy, radius, count, startAngle, endAngle), grid-group (matrix: cols, rows, colSpacing, rowSpacing), scatter-group (random: width, height, count, seed), path-group (along polyline: waypoints, count). Each takes ONE "child" element.
Parametric curves (fn field): rose, heart, lissajous, spiral, star, superformula, epitrochoid, hypotrochoid, wave. Size via "scale" field. Server computes coordinates.
defs: gradients (linear/radial, SMIL animated stops), filters (presets: glow, neon, blur, drop-shadow, glitch, chromatic-aberration, noise, outline, inner-shadow, emboss + 5 more), clipPaths, masks, patterns (tile fills).
Animations: CSS @keyframes via animations array. Set cssClass on element matching animation name. For transforms add transformBox="fill-box" transformOrigin="center". SMIL via smilAnimations on elements (animate, animateTransform, animateMotion).
Critical format rules:
Gradient type must be "linearGradient" or "radialGradient" (not "linear"/"radial"). Each needs id, stops (array with offset 0-1, color).
Filter type must be "preset" with a "preset" field: {"type":"preset","id":"myGlow","preset":"glow","stdDeviation":8,"color":"#ff00ff"}
Keyframe offset: use "from"/"to" or percentage number 0-100 (not "0%"/"100%").
Gradient stop and filter colors: hex only (#rrggbb or #rrggbbaa). Element fill/stroke accept '#rrggbb', 'none', or 'url(#id)' (hex is safest).
Every element needs "type" field. circle needs r, rect needs width+height, path needs d.
Field names that differ from raw SVG:
text: string goes in "content" (not "text"): {"type":"text","x":100,"y":50,"content":"Hello","fontSize":24,"textAnchor":"middle"}
textPath: {"type":"textPath","pathId":"idFromDefsPaths","text":"..."} — here the field IS "text".
group: {"type":"group","children":[...]} — children are shapes/text/use only, no nested groups.
Pattern groups take ONE "child" element drawn at local origin (child uses cx=0/cy=0); set rotateChildren:false to keep text upright.
Output: Pure SVG XML. No JavaScript. CSS @keyframes + SMIL only.
Inputs: canvas (required), elements (required), defs, output, +1 more.
saveSave ContentA
Save rendered content to disk. Format-aware: can save as text or render to raster image.
IMPORTANT: Use this only AFTER iterating on the design with render_svg's preview images. Do not save on the first render. Preview and refine your work first.
Input: pass EITHER artifact (id from render_svg, e.g. "art-1" — preferred, no SVG resend) OR content (raw string).
Format detection:
'auto' (default): infers format from file extension. .svg saves as text, .png renders to image.
'svg': saves content as a UTF-8 text file
'png': renders the content (assumed SVG) to a PNG image, then saves it
If the file already exists, a numeric counter is appended before the extension to prevent overwriting: design.svg becomes design-1.svg, then design-2.svg. The actual saved path is returned in the response.
Inputs: outputPath (required), width, format, content, +1 more.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 3 tools
Each tool has a clearly distinct purpose: render_svg generates SVG from config, preview renders existing or external SVG to PNG, and save persists rendered content. The overlap where render_svg includes a preview by default is explicitly handled by the preview tool's description, so no ambiguity exists.
All names use lowercase snake_case and are short, but there is a minor deviation: render_svg follows verb_noun while preview and save are bare verbs. The pattern is still predictable and readable, with only a slight structural inconsistency.
Three tools is well-scoped for a focused SVG rendering service. Each tool earns its place: render for creation, preview for inspection, save for persisting output. No unnecessary duplication or bloat.
The tool surface covers the full intended workflow: render generated content, preview it at different sizes or from external SVG, and save as text or image. There are no obvious dead ends or missing core operations for the server's stated purpose.
Maintenance
Related MCP Connectors
SVG Lab MCP: the Design Engine for AI. App screens, icons, illustrations and charts as SVG.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models and 10 tools: up to 4 images per call, SVG vectorization, editing and more. Remote MCP with OAuth, no API keys. Pay per image, no subscription.
Generate images from Claude, ChatGPT, Cursor and Codex with 12 top AI image models. Up to 4 images per call, SVG vectorization, background removal, upscaling and image-to-video. Remote MCP with OAuth, no API keys.
MCP server for Flux AI image generation
Related MCP Servers
- AlicenseAqualityCmaintenanceEnables AI models to generate interactive visuals including charts, diagrams, UI mockups, and SVG graphics from plain text prompts. This Windows-based MCP server serves as an intermediary to bridge AI tools with visual output capabilities.178 npmMIT
- AlicenseBqualityBmaintenanceMCP server that lets AI agents drive Inkscape — interactively alongside the GUI or headlessly from the CLI8966 PyPI93MIT
- AlicenseCqualityCmaintenanceMCP server for creating and manipulating generative art with p5.js, Three.js, GLSL, Canvas2D, and SVG, featuring workspace management, parameter control, and screenshot capture.312134 npmMIT
- AlicenseNot gradedqualityBmaintenanceA FastMCP server providing structured SVG authoring tools for LLMs, enabling create, edit, and render SVG graphics through hierarchical primitives, gradients, paths, and reusable resources.780 PyPI11GPL 2.0