imagetosvg-mcp

A local Model Context Protocol server that gives AI agents full control over images — vectorize a raster image, import a vector file (PDF/AI/EPS), then inspect, edit, render, and optimize the SVG. No API keys, no cloud; everything runs locally.

The idea: an SVG is just text, and the agent is already the intelligence. So this server only does what an agent can't do on its own — turn pixels into editable paths and render SVG back to a picture for visual verification — plus a set of structured edit operations for the parts of SVG editing that are tedious by hand. The agent does the rest with its own file tools.

Why

Agents normally treat an image as opaque pixels they can't change. Convert it to SVG and the agent can recolor a logo, delete a layer, resize, restyle, or simplify it — then render the result and see whether the edit worked, all deterministically.

Tools

Tool	Purpose
convert_image_to_svg	Raster → SVG (hybrid: clean trace for simple graphics, layered color trace for complex ones)
import_vector	PDF / AI / EPS → SVG (paths preserved, no tracing)
inspect_svg	List addressable layers (id, tag, fill, stroke, bbox) without parsing path strings
edit_svg	Structured edits by layer id (recolor, remove, isolate, transform, resize, set attribute)
render_svg	Rasterize SVG → PNG so the agent can verify visually
optimize_svg	Clean up with svgo while preserving layer ids and viewBox

Supported raster inputs: PNG, JPG, WebP, GIF, BMP, TIFF, AVIF. Supported vector inputs: PDF, PDF-compatible AI, and EPS (EPS requires Ghostscript).

Install

git clone https://github.com/ujo78/imagetosvg-mcp.git
cd imagetosvg-mcp
npm install        # builds automatically (prepare hook)

Requires Node.js >= 20. All native dependencies ship prebuilt binaries — no system toolchain required.

Connect it to an agent

Claude Code

User scope (available in every project):

claude mcp add -s user imagetosvg -- node "/absolute/path/to/imagetosvg-mcp/dist/index.js"

Or per-project, commit a .mcp.json at the repo root:

{
  "mcpServers": {
    "imagetosvg": {
      "command": "node",
      "args": ["/absolute/path/to/imagetosvg-mcp/dist/index.js"]
    }
  }
}

Claude Desktop / Cursor / Windsurf

Add the same block to the client's MCP config (claude_desktop_config.json for Claude Desktop; the MCP settings panel for Cursor/Windsurf). Use an absolute path to dist/index.js.

On Windows, use forward slashes in the path, e.g. C:/Users/you/imagetosvg-mcp/dist/index.js.

The workflow

The bundled Claude skill teaches agents this loop:

1. Look at the source image.
2. Convert (convert_image_to_svg) or import (import_vector); check the returned PNG preview.
3. Compare preview to the original; re-convert with a different mode/max_colors if needed.
4. Inspect (inspect_svg) to learn the layers.
5. Edit with edit_svg (structured) or the agent's own file tools (freeform).
6. Verify with render_svg and look. Iterate.
7. Finalize with optimize_svg and use the .svg in place of the image.

edit_svg operations

setFill{id,color}, setStroke{id,color}, removeNode{id}, isolateNode{id}, transform{id,translate?,scale?,rotate?}, setDimensions{width?,height?}, setAttribute{id,name,value}. Layer ids (layer-N) are assigned in document order and survive optimize_svg.

Optional: EPS support

EPS import requires Ghostscript on PATH (gswin64c on Windows). PDF and AI work without it; if Ghostscript is missing, import_vector returns a clear error for EPS only.

Development

npm run dev        # run the server from source via tsx
npm run typecheck  # tsc --noEmit
npm test           # vitest
npm run build      # tsc -> dist/

See CONTRIBUTING.md for the full guide.

How it works

• Hybrid conversion: a unique-color heuristic classifies an image as simple (vtracer binary trace → clean paths) or layered (vtracer color trace → stacked, individually addressable color layers). Override with mode / max_colors.
• Vector import: PDF/AI go through mupdf (WASM, no system deps) with paths preserved; EPS is converted via Ghostscript when available.
• Stack: TypeScript (ESM) · @modelcontextprotocol/sdk · @neplex/vectorizer (vtracer) · sharp · @resvg/resvg-js · svgo · svgson.

License

MIT © Rakshit Raj