svgwriter-mcp

An MCP server that wraps the svgwrite Python library, enabling LLM agents to create, compose, and export SVG documents through tool calls.

Features

• 21 tools covering the full SVG creation workflow
• In-memory document state — create multiple documents in a session
• Groups, gradients, shapes, text, paths, and pattern generators
• Returns SVG as a string or saves directly to disk

Installation

git clone <repo>
cd svgwriter-mcp
uv sync

Usage

As an MCP server (stdio)

uv run python main.py

As a library (direct function calls)

import json, server

result = json.loads(server.create_document(width="800px", height="600px"))
doc_id = result["doc_id"]

server.add_rect(doc_id=doc_id, x=0, y=0, width=800, height=600, fill="#eef")
server.add_text(doc_id=doc_id, text="Hello SVG", x=400, y=300, text_anchor="middle")

server.save_file(doc_id=doc_id, filepath="hello.svg")

Run the demo

uv run python example.py
# produces example_output.svg

MCP Client Configuration

Add to your Claude Desktop claude_desktop_config.json (%APPDATA%\Claude\claude_desktop_config.json on Windows, ~/Library/Application Support/Claude/claude_desktop_config.json on macOS):

{
  "mcpServers": {
    "svgwriter": {
      "command": "uv",
      "args": [
        "run",
        "python",
        "/path/to/svgwriter-mcp/main.py"
      ]
    }
  }
}

Note: Use the absolute path to main.py on your machine (e.g. C:\\Users\\you\\svgwriter-mcp\\main.py on Windows). Using the full path avoids working-directory issues with Claude Desktop.

Tool Reference

Document Lifecycle

Tool	Description
create_document	Create a new SVG document; returns doc_id
list_documents	List all open documents with their sizes
delete_document	Delete a document and free its state
get_svg_string	Return the SVG XML as a raw string
get_svg_preview	Return the SVG as an inline image/svg+xml content block for visual preview
save_file	Write the SVG to a file on disk

Shapes

All shape tools accept an optional group_id to target a group instead of the document root.

Tool	Key Parameters
add_circle	cx, cy, r, fill, stroke
add_rect	x, y, width, height, rx, ry
add_line	x1, y1, x2, y2, stroke
add_ellipse	cx, cy, rx, ry
add_text	text, x, y, font_size, font_family, text_anchor
add_polygon	points (list of [x, y] pairs)
add_path	d (SVG path data string)

Groups

Tool	Description
create_group	Create a <g> element; optionally set opacity or transform
list_groups	List all group ids in a document

Gradients

Use the returned url_ref (e.g. url(#grad1)) as a fill value for shapes.

Tool	Description
add_linear_gradient	Add a linearGradient; specify stops, x1/y1/x2/y2
add_radial_gradient	Add a radialGradient; specify stops, cx/cy/r/fx/fy
list_gradients	List all gradients in a document

Pattern Generators

Tool	Description
add_grid_pattern	Grid of lines at cell_size intervals
add_checkerboard_pattern	Alternating color1/color2 squares
add_dot_grid_pattern	Small circles at spacing intervals
add_concentric_circles_pattern	Circles from min_radius to max_radius

Development

# Install with dev deps
uv sync --group dev

# Run tests
uv run pytest -v

# Syntax check
uv run python -c "import server; print('OK')"

Response Format

All tools return a JSON string:

{"status": "ok", "doc_id": "doc_abc123"}
{"status": "error", "message": "Document 'x' not found."}