# arikusi/nakkas [Health: Active]

**Category:** 🎨 Art & Culture  
**Repository:** https://github.com/arikusi/nakkas  
**GitHub Stars:** 30  
**npm Downloads (last month):** 646  
**Views:** 4  
**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

## What arikusi/nakkas MCP server does

The arikusi/nakkas MCP server converts structured JSON into SVG artwork for use in logos, icons, loading indicators, README banners, badges, charts, and generative designs. Its output is pure SVG XML, with animation provided by CSS `@keyframes` and SMIL rather than JavaScript. The renderer can also produce a PNG image so an AI assistant can inspect the result.

The main generation tool accepts an SVG configuration containing a canvas, optional definitions, elements, animations, and output preferences. Each element requires a `type` field. Supported shapes include rectangles, circles, ellipses, lines, paths, polygons, images, text, text paths, groups, instances, and several pattern-oriented group types. Parametric elements can generate rose, heart, Lissajous, spiral, star, superformula, epitrochoid, hypotrochoid, and wave curves.

## How it works

A typical workflow starts with `render_svg`. The server keeps the generated SVG as an artifact and returns its identifier with a PNG preview. The assistant can inspect that image, adjust the JSON, and render another version without sending the full SVG through its context. The supplied workflow recommends several preview-and-revision passes before saving.

The `preview` tool can render an existing artifact or raw SVG at a selected width. A normal preview represents the initial animation state, while the `frames` option creates a filmstrip of two to ten sampled CSS-animation states. This helps check rotation, timing, easing, and other motion details. SMIL animation is not included in those sampled frames.

The `save` tool accepts an artifact ID or raw SVG. It can write SVG text or rasterize the content to PNG. Automatic format selection uses the output filename extension, and an existing file receives a numeric suffix instead of being overwritten. Artifacts remain available only for the server process lifetime, with a maximum of 32 stored and older entries evicted.

## Setup and configuration

The arikusi/nakkas MCP server runs locally through the npm package and does not require cloud credentials or API keys. For Claude Desktop, Cursor, Zed, and similar MCP clients, configure a server command using `npx -y nakkas@latest`. Claude Code can add the same server with `claude mcp add nakkas npx nakkas@latest`.

For development, clone the repository, run `npm install && npm run build`, and use `dist/index.js` as the command. No environment variables are specified as required.

Configurations must use the server's field names rather than assuming raw SVG syntax. Text uses `content`, text paths use `pathId`, and groups use a `children` array. Pattern groups accept one child positioned at the local origin. Gradients use `linearGradient` or `radialGradient`; filters use the `preset` form when selecting a built-in filter. Hex colors are required for gradient stops and filter colors, and keyframe offsets use `from`, `to`, or numeric percentages.

## Tools and capabilities

- `render_svg`: Generates animated SVG from JSON and returns a PNG preview, artifact ID, and possible design-analysis notes.
- `preview`: Re-renders an artifact or raw SVG, optionally at a different width.
- `save`: Writes an artifact or raw SVG as SVG text or PNG image.
- Definitions can include gradients, filters, clipping paths, masks, patterns, markers, symbols, and reusable paths.
- Pattern groups support radial, arc, grid, scatter, and path-based repetition.
- Built-in filter presets include effects such as glow, neon, blur, drop shadow, glitch, noise, outline, and emboss.
- Output options can include the SVG text, skip the preview, resize the preview, minify stored output, or generate animation filmstrips.

## Limitations and notes

A single preview shows a static snapshot, so it does not establish that an animation behaves correctly. Use sampled frames for CSS motion; SMIL remains unsampled. The renderer returns transparent backgrounds by default unless the canvas specifies another background.

Pattern-group children are constrained to one element, and nested groups are not supported inside the ordinary `group` element. For radial or arc arrangements, children are expected to be drawn along the local x-axis when rotation is enabled; using the y-axis can produce an unintended chord-like ring. The server may report overflow, text overlap, missing transform settings, excessive concurrent animation, or contrast issues after rendering. These notes are checks to review, not automatic design fixes.

_Full upstream README: https://allmcps.com/mcp/arikusi-nakkas/readme_