svg-mcp

svg-mcp

📖 Rendered documentation: docs.georgeharker.com/svg-mcp — with a gallery and cookbook.

A FastMCP server that exposes structured, hierarchical SVG authoring to an LLM — all primitives, gradients/patterns, paths, text-on-path, embedded raster, reusable styles — built around an inkex-backed document model the AI can navigate, query, and manipulate as groups, layers, transforms, and masks, with a fast construct → render → see → iterate loop.

The logo above was authored entirely through these tools — see Usage.

See DESIGN.md for the full architecture and the INKEX_PRIMITIVES.md catalog for the inkex → tool mapping.

Quickstart

1. Prerequisites — Python ≥ 3.12 and uv. Every path below runs svg-mcp through uv — standalone and the Claude Code plugin — so install it first if you don't have it:

   curl -LsSf https://astral.sh/uv/install.sh | sh   # macOS / Linux
   # alternatives: brew install uv  ·  pipx install uv  ·  winget install astral-sh.uv (Windows)
   

   Rendering happens in-process (the resvg engine ships as the resvg-py dependency), so there's no separate renderer to install. Optionally, install the resvg CLI for a small per-render speedup — used automatically when on PATH:

   brew install resvg          # OPTIONAL (macOS; or: cargo install resvg)
   

   Linux build headers. On macOS the install is pure wheels. On Linux, two dependencies — lxml and PyGObject (the latter pulled in by inkex) — sometimes have no matching wheel for a recent interpreter and are compiled from source by pip, which needs C headers. Install them up front (see System packages (Linux) for the full per-library mapping and other distros). On Debian 13 (trixie) / Ubuntu:

   sudo apt-get install build-essential python3-dev pkg-config \
       libxml2-dev libxslt1-dev libglib2.0-dev \
       libgirepository-2.0-dev gir1.2-girepository-2.0 libcairo2-dev
   

2. Install.

   Recommended — no clone. Install svg-mcp into an environment you manage, so the entrypoint is stable and launches fast (no per-invocation dependency resolution):

   uv tool install svg-mcp                                   # isolated tool; `svg-mcp` on PATH
   # into your own venv instead:  uv pip install svg-mcp      # (with that venv active)
   # track main (pre-release):    uv tool install "git+https://github.com/georgeharker/svg-mcp"
   

   → entrypoint: svg-mcp (absolute: which svg-mcp, usually ~/.local/bin/svg-mcp), or /path/to/your/venv/bin/svg-mcp for the uv pip install case.

   💡 Avoid uvx svg-mcp as the MCP server command: uvx re-resolves dependencies on every launch — needless latency for a long-lived server. Install once (above) and point your client at the resulting entrypoint.

   Alternative: install from a clone (for development)

   Pick one of two install layouts — this choice decides the path you point Claude at:

   a) Project-local venv (self-contained). Creates ./.venv inside the repo and installs svg-mcp editable into it — nothing touches your other environments:

   uv sync                             # → ./.venv with svg-mcp + deps (from pyproject/uv.lock)
   # equivalently, without uv.lock:  uv venv && uv pip install -e .
   

   → entrypoint: ./.venv/bin/svg-mcp (absolute: $(pwd)/.venv/bin/svg-mcp).

   b) Into your own existing venv. Activate the venv you want first, then install editable:

   source /path/to/your/venv/bin/activate      # or otherwise have VIRTUAL_ENV set
   uv pip install -e .                          # or: pip install -e .
   

   → entrypoint: /path/to/your/venv/bin/svg-mcp.

   ⚠️ uv sync always targets the project's ./.venv, but uv pip install / pip install target whichever venv is currently active. If you already have one active, svg-mcp and its dependencies (fastmcp, inkex, fontTools, numpy, Pillow, …) get installed into it. Use option (a) — or an explicit fresh venv — unless you deliberately want it in an existing environment.