# Svgshot

> SVGShot — Animated SVG creator & screenshot tool with CSS animation-aware capture. Render, filmstrip, and diff animated SVGs the way users actually see them.

- **Type:** MCP server
- **Install:** `agentstack add mcp-busybee3333-svgshot`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [BusyBee3333](https://agentstack.voostack.com/s/busybee3333)
- **Installs:** 0
- **Category:** [Web & Browser](https://agentstack.voostack.com/c/web-and-browser)
- **Latest version:** 0.1.0
- **License:** Apache-2.0
- **Upstream author:** [BusyBee3333](https://github.com/BusyBee3333)
- **Source:** https://github.com/BusyBee3333/svgshot

## Install

```sh
agentstack add mcp-busybee3333-svgshot
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# SVGShot — Animated SVG Creator & Screenshot Tool

> **Create, preview, and QA animated SVGs** with CSS animation-aware screenshots. The open-source animated SVG creator tool that captures what users actually see — not a blank screen at t=0.

[](LICENSE)
[](https://nodejs.org)
[](https://modelcontextprotocol.io)

## The Problem Every SVG Creator Faces

Every SVG screenshot tool renders at **t=0** — the instant the page loads. CSS animations that start with `opacity: 0` are **invisible** in the screenshot, even though users see them animate in within milliseconds.

**Your animated SVGs look empty in previews, CI screenshots, and AI-assisted design workflows.**

SVGShot fixes this with animation-aware capture modes that screenshot your SVGs the way users actually experience them.

## Features

- **🎬 Animation-Aware SVG Screenshots** — Capture animated SVGs mid-animation, at their final state, or frame-by-frame
- **🎞️ Filmstrip Mode** — Generate multi-frame strips showing the full SVG animation progression at configurable intervals
- **🔍 Visual Diff** — Pixel-level comparison between two versions of your SVG or HTML
- **🤖 MCP Server** — Drop-in tool for Claude Code, Cursor, and any MCP-compatible AI agent
- **🌐 REST API** — Simple HTTP endpoints for any SVG creator workflow or CI pipeline
- **⚡ Fast** — Shared Playwright browser instance, 2-second renders, no cold starts after first request
- **🎨 SVG + HTML + React** — Auto-detects input format, wraps SVG/snippets in proper boilerplate with Tailwind CDN

## Quick Start

```bash
git clone https://github.com/BusyBee3333/svgshot.git
cd svgshot
npm install
npx playwright install chromium
npm start
# Server running at http://localhost:3700
```

## SVG Animation Capture Modes

The core innovation — four ways to capture animated SVG content:

| Mode | What It Does | Best For |
|------|-------------|----------|
| **`natural`** | Waits configurable delay (default 800ms) then screenshots | Animated SVGs — captures mid-animation state like users see |
| **`freeze-end`** | Injects CSS to force all SVG animations to their final state | Static previews of fully-settled designs |
| **`filmstrip`** | Captures N frames at intervals, composites into one image | SVG animation QA — verify timing, opacity ramps, transitions frame by frame |
| **`instant`** | Screenshots immediately at page load (t=0) | Static SVGs or comparing with the t=0 bug behavior |

### How `freeze-end` Works

Injects this CSS before capture to jump every CSS animation to its end state:

```css
*, *::before, *::after {
  animation-delay: -9999s !important;
  animation-duration: 0.001s !important;
  animation-fill-mode: both !important;
  transition-duration: 0s !important;
  transition-delay: 0s !important;
}
```

### SVG Filmstrip Example

Capture 8 frames over 2 seconds to verify your animated SVG output:

```bash
curl -X POST http://localhost:3700/filmstrip \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "...",
    "frames": 8,
    "duration": 2000,
    "layout": "horizontal",
    "showTimestamps": true
  }' --output filmstrip.jpg
```

Returns a single composite image with all frames side by side, each labeled with its timestamp. Perfect for verifying CSS animation timing in your SVG creator workflow.

## REST API (Port 3700)

### POST /render — Screenshot SVG or HTML

```bash
curl -X POST http://localhost:3700/render \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "@keyframes fadeIn{from{opacity:0}to{opacity:1}} circle{animation:fadeIn 1s forwards}",
    "viewport": { "width": 400, "height": 400 },
    "quality": 90,
    "animationMode": "natural",
    "screenshotDelay": 1000
  }' --output screenshot.jpg
```

**Parameters:**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `code` | string | required | SVG, HTML, or React code to render |
| `viewport` | object | `{width:1280, height:800}` | Viewport dimensions |
| `quality` | number | `85` | JPEG quality (1-100) |
| `fullPage` | boolean | `false` | Capture full scrollable page |
| `animationMode` | string | `"natural"` | `natural`, `freeze-end`, or `instant` |
| `screenshotDelay` | number | `800` | Milliseconds to wait before capture (natural mode) |

**Response:** JPEG image buffer with headers:
- `X-Console-Errors` — JSON array of JS console errors during render
- `X-Render-Meta` — JSON object with render metadata

### POST /filmstrip — SVG Animation Frame Strip

```bash
curl -X POST http://localhost:3700/filmstrip \
  -H 'Content-Type: application/json' \
  -d '{
    "code": "...",
    "frames": 6,
    "duration": 2000,
    "layout": "grid",
    "showTimestamps": true
  }' --output filmstrip.jpg
```

**Parameters:**

| Param | Type | Default | Description |
|-------|------|---------|-------------|
| `code` | string | required | SVG or HTML to capture |
| `viewport` | object | `{width:800, height:600}` | Per-frame viewport |
| `quality` | number | `85` | JPEG quality |
| `frames` | number | `6` | Number of frames to capture |
| `duration` | number | `2000` | Total duration to capture (ms) |
| `layout` | string | `"horizontal"` | `horizontal`, `vertical`, or `grid` |
| `showTimestamps` | boolean | `true` | Show timestamp labels on each frame |

### POST /diff — Visual Diff Two SVG Versions

```bash
curl -X POST http://localhost:3700/diff \
  -H 'Content-Type: application/json' \
  -d '{
    "before": "",
    "after": ""
  }'
```

**Response:**
```json
{
  "diffPercent": 2.45,
  "totalPixels": 1024000,
  "changedPixels": 25088,
  "dimensions": { "width": 1280, "height": 800 }
}
```

### GET /health

```json
{ "status": "ok", "service": "svgshot", "version": "1.0.0" }
```

## MCP Server — AI-Powered SVG Creator Integration

Use SVGShot as an MCP tool in Claude Code, Cursor, Windsurf, or any MCP-compatible AI coding agent. The AI can create animated SVGs, render them, see the output, and iterate — all in one conversation.

### Add to Claude Code

```bash
claude mcp add svgshot -- node /path/to/svgshot/src/mcp.js
```

### Add to Cursor / Windsurf / Other MCP Clients

```json
{
  "mcpServers": {
    "svgshot": {
      "command": "node",
      "args": ["/path/to/svgshot/src/mcp.js"]
    }
  }
}
```

### MCP Tools

| Tool | Description |
|------|-------------|
| **`render`** | Full SVG/HTML render with all options — returns base64 JPEG + metadata |
| **`render_svg`** | SVG convenience wrapper — auto-sets natural mode + 1000ms delay |
| **`filmstrip`** | Capture SVG animation as multi-frame composite strip |
| **`diff`** | Visual diff between two SVG/HTML versions — returns diff image + percentage |

## Use Cases

### Animated SVG Creator Workflow
1. Create your SVG with CSS `@keyframes` animations
2. Render with `natural` mode to see what users actually experience
3. Use `filmstrip` to verify animation timing frame by frame
4. Iterate until perfect, then ship

### SVG QA in CI/CD
```bash
# Render all SVGs and check for console errors
for svg in assets/*.svg; do
  curl -s -X POST http://localhost:3700/render \
    -H 'Content-Type: application/json' \
    -d "{\"code\": $(jq -Rs . < "$svg")}" \
    -D - -o /dev/null | grep X-Console-Errors
done
```

### SVG Visual Regression Testing
```bash
# Diff before and after an SVG change
curl -X POST http://localhost:3700/diff \
  -H 'Content-Type: application/json' \
  -d "{\"before\": $(cat before.svg | jq -Rs .), \"after\": $(cat after.svg | jq -Rs .)}"
```

### AI-Assisted Animated SVG Design
With the MCP server, your AI coding agent can:
- Create animated SVGs from text descriptions
- Render them immediately to verify the visual output
- See what's wrong and fix it in the same conversation
- Use filmstrip to verify SVG animation timing
- Iterate until the animation is perfect — no more blind SVG coding

## Architecture

```
svgshot/
  src/
    server.js       — Express REST server (port 3700)
    mcp.js          — MCP stdio server (4 tools)
    renderer.js     — Core Playwright engine + filmstrip
    differ.js       — Pixel diff (pixelmatch)
  package.json
  start.sh          — Start REST server
  mcp.sh            — Start MCP server
  LICENSE           — Apache 2.0
```

- **Shared browser instance** — Playwright Chromium reused across requests
- **2x device scale** — Retina-quality SVG screenshots by default
- **Auto-detect format** — SVG, HTML snippets, and full HTML documents handled automatically
- **Tailwind CDN** — Included by default for HTML snippet rendering
- **Graceful shutdown** — Clean browser teardown on SIGTERM/SIGINT

## Requirements

- Node.js 18+
- Playwright Chromium (`npx playwright install chromium`)

## License

Apache License 2.0 — see [LICENSE](LICENSE) for details.

---

**Built for the animated SVG creator community** — because animated SVGs deserve screenshots that actually show the animations.

## Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

- **Author:** [BusyBee3333](https://github.com/BusyBee3333)
- **Source:** [BusyBee3333/svgshot](https://github.com/BusyBee3333/svgshot)
- **License:** Apache-2.0

Install and usage instructions live in the source repository linked above.

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-busybee3333-svgshot
- Seller: https://agentstack.voostack.com/s/busybee3333
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.