# arikusi/nakkas [Health: Active]
**Category:** π¨ Art & Culture
**Repository:** https://github.com/arikusi/nakkas
**GitHub Stars:** 22
**Views:** 2
**Installs:** 0
**Upvotes:** 0
**Directory Page:** https://allmcps.com/mcp/arikusi-nakkas
## Description
MCP server that turns AI into an SVG artist. One rendering engine with JSON config, AI controls all design parameters. CSS @keyframes + SMIL animations, 16+ element types, parametric curves, filters, gradients, PNG preview.
## Tools
Capabilities this server exposes over MCP:
- **render_svg** β 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).
**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. The child is drawn at the local origin and, with rotateChildren true (the default), rotates so local +x points outward from the center: draw spokes, rays and petals long along the x axis, never the y axis, or they render as a chord ring.
**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), markers (arrowheads: triangle, arrow, circle, square, diamond, bar; set markerStart/markerEnd:"id" on line/polyline/path, scales with strokeWidth).
**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).
**Design guide (what makes output look good):** Pick one spacing unit (e.g. 8) and use multiples of it for every gap and margin; keep content clear of the canvas edges by at least 5% of the smaller dimension (the bbox audit reports overflow in px). Use at most 3 font sizes per design with clear jumps (e.g. 12/16/24). Body-size text needs 4.5:1 contrast against its background, 3:1 from 24px up (the contrast audit checks plain hex pairs). Text ink boxes are measured after every render; escaping or overlapping text comes back as a named design note. Motion: ease-out for entrances, ease-in-out for back-and-forth loops, linear only for continuous rotation or travel; 0.8-3s durations read well for UI-scale loops.
**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.
- **preview** β 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)
- **save** β 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.
## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):
```json
"mcpServers": {
"nakkas": {
"command": "npx",
"args": ["-y","nakkas@latest"]
}
}
```
## Documentation & README
MCP server that turns AI into an SVG artist.
One rendering engine. AI decides everything.
Officially listed on the MCP Registry, Glama, LobeHub, and PulseMCP.
Both drawn by an AI through nakkas, one JSON config each, iterated against its own PNG previews. Pure CSS animation, no JavaScript.
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 `![]()
` 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`
```json
{
"mcpServers": {
"nakkas": {
"command": "npx",
"args": ["-y", "nakkas@latest"]
}
}
}
```
### Claude Code (CLI)
```bash
claude mcp add nakkas npx nakkas@latest
```
### Cursor / Zed / Other MCP clients
```json
{
"mcpServers": {
"nakkas": {
"command": "npx",
"args": ["-y", "nakkas@latest"]
}
}
}
```
### Local Development
```bash
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:
| Tool | Purpose |
|---|---|
| `render_svg` | Takes SVGConfig JSON, returns a PNG preview + artifact id (+ design analysis warnings) |
| `preview` | Re-renders a stored artifact (or raw SVG) to PNG at any width |
| `save` | 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
```json
{ "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:
```json
{ "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
```typescript
{
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 |
|------|----------------|-------|
| `rect` | `width`, `height` | `x`, `y` default 0; `rx`/`ry` for rounded corners |
| `circle` | `r` | `cx`, `cy` default 0 |
| `ellipse` | `rx`, `ry` | Independent horizontal/vertical radii |
| `line` | `x1`, `y1`, `x2`, `y2` | `markerStart`/`markerEnd` take a marker id from `defs.markers` |
| `polyline` | `points` | Open path: `"10,20 50,80 90,20"`; supports `markerStart`/`markerMid`/`markerEnd` |
| `polygon` | `points` | Auto-closed shape |
| `path` | `d` | Full SVG path commands |
| `image` | `href`, `width`, `height` | URL or `data:image/...` URI for embedded images |
| `text` | `content` | String or `(string \| Tspan)[]` array |
| `textPath` | `pathId`, `text` | Text following a curve; path defined in `defs.paths` |
| `group` | `children` | Shared attrs applied to all children (no nested groups) |
| `use` | `href` | Instance a symbol or clone an element by `#id` |
| `radial-group` | `cx`, `cy`, `count`, `radius`, `child` | Place N copies around a full circle |
| `arc-group` | `cx`, `cy`, `radius`, `count`, `startAngle`, `endAngle`, `child` | Place N copies along a circular arc |
| `grid-group` | `cols`, `rows`, `colSpacing`, `rowSpacing`, `child` | Place copies in an M by N grid |
| `scatter-group` | `width`, `height`, `count`, `seed`, `child` | Scatter N copies at seeded random positions |
| `path-group` | `waypoints`, `count`, `child` | Distribute N copies evenly along a polyline |
| `parametric` | `fn` | Mathematical curve: `rose`, `heart`, `star`, `lissajous`, `spiral`, `superformula`, `epitrochoid`, `hypotrochoid`, `wave` |
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)
```typescript
{
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`:
```json
{ "type": "preset", "id": "myGlow", "preset": "glow", "stdDeviation": 8, "color": "#ff00ff" }
```
| Preset | Key params | Effect |
|--------|-----------|--------|
| `glow` | `stdDeviation`, `color` | Soft halo |
| `neon` | `stdDeviation`, `color` | Intense bright glow |
| `blur` | `stdDeviation` | Gaussian blur |
| `drop-shadow` | `stdDeviation`, `offsetX`, `offsetY`, `color` | Drop shadow |
| `glitch` | `stdDeviation` | Turbulence displacement (animated) |
| `grayscale` | `value` (0β1) | Desaturate |
| `sepia` | β | Warm sepia tone |
| `invert` | β | Invert colors |
| `saturate` | `value` | Boost/reduce saturation |
| `hue-rotate` | `value` (degrees) | Shift hues |
| `chromatic-aberration` | `value` (px offset, default 3) | RGB channel split for lens distortion look |
| `noise` | `value` (opacity 0 to 1, default 0.25) | Film grain and texture overlay |
| `outline` | `color`, `value` (thickness, default 2) | Colored outline around the element |
| `inner-shadow` | `color`, `stdDeviation`, `value` (opacity, default 0.5) | Shadow inside the element |
| `emboss` | `stdDeviation`, `value` (intensity, default 1.5) | 3D relief shading effect |
### CSS Animations
```json
{
"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: []`:
```json
{ "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 `0` or `100` (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"` or `rgb()`. Element `fill`/`stroke` accept any paint string (`"#ff0000"`, `"none"`, `"url(#id)"`), with hex being the safest choice across renderers.
* **Missing `type` on elements.** Every element object needs a `type` field.
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](https://github.com/anthropics/claude-code/issues/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 `fill` or `stroke` set. A shape without fill on a transparent canvas is invisible.
* Check coordinates. An element at `x: 2000` on an `800px` wide canvas is simply off-screen.
* If using `filter: "url(#myFilter)"`, make sure `myFilter` is actually defined in `defs.filters`.
### Animations not working on GitHub
GitHub READMEs render SVG through `![]()
` tags, which strips JavaScript but keeps CSS and SMIL. If your animation works locally but not on GitHub:
* Avoid `