inkscape_mcp
Allows AI agents to design, edit, and analyze vector graphics through Inkscape, enabling operations like path editing, format conversion, effects, barcode generation, and live canvas interaction.
Inkscape MCP
Let your AI agent design, edit, and analyze vector graphics through Inkscape — live alongside a running Inkscape window, or headless from the command line.
With Inkscape MCP, your coding agent can do everything a designer does in Inkscape — sketch and reshape paths, apply effects and filters, render LaTeX equations, generate barcodes and QR codes, convert between formats, query and rewrite document structure — through plain conversation instead of menu clicks.
Pair it with a running Inkscape window and the agent works alongside you — it sees what you have selected, opens property dialogs on your behalf, applies edits that appear on the canvas in real time (each one a normal undo entry you can roll back), and rasterizes its own work to inspect and refine the result. Or run it headlessly to batch-convert artwork, automate exports, and build pipelines around vector assets — no GUI required. The full Inkscape feature surface, including its hundreds of bundled extensions, is reachable as tool calls.
How it works
The agent calls one of eight portmanteau tools —
inkscape_file,inkscape_vector,inkscape_analysis,inkscape_system,inkscape_extension,inkscape_gradient,inkscape_metadata, orinkscape_live— with anoperationstring that picks the actual behavior.For headless work the server dispatches through
InkscapeCliWrapper, which builds and runs aninkscape --actions=...(or--export-...) command. For live-canvas work it talks to a running Inkscape window over D-Bus and inserts SVG fragments through the XML-edit extension.Inkscape reads your input file (or the open document), runs the operation, and writes the output.
The server returns dimensions, file paths, validation results, or whatever the operation produces — typed and trimmed for the agent's context window.
No external network. Just the Inkscape binary, an optional running Inkscape window, and your local files.
Related MCP server: nakkas
Getting started
Tested with Inkscape 1.4.4 on Ubuntu 24.04, Windows 11, and macOS (Apple Silicon).
# 1. Install Inkscape + system headers for pycairo / pygobject
sudo add-apt-repository ppa:inkscape.dev/stable
sudo apt update
sudo apt install inkscape libcairo2-dev libgirepository-2.0-dev libgirepository1.0-dev \
pkg-config python3-dev
# 2. Register with Claude Code (uvx fetches inkscape-mcp from PyPI on first run)
claude mcp add inkscape_mcp -s user -- uvx inkscape_mcp
claude mcp list | grep inkscape_mcp # → ✓ Connected
# 3. (Re)start Inkscape so it picks up the bundled extensions
# The MCP server auto-installs its inkex extensions to
# ~/.config/inkscape/extensions/inkscape_mcp/ on first boot. Inkscape only
# scans the extensions dir at startup, so close + reopen Inkscape once.
# Verify via:
# inkscape_system(operation="diagnostics") → bridge.needs_restart should be falseThat's it. Ask the agent to convert an SVG, query an object's bounding box, run a boolean union — it'll pick the right tool.
Alternative install paths
# Plain pip into a venv
pip install inkscape-mcp
# uv into a project
uv add inkscape-mcpThe PyPI name is inkscape-mcp (hyphen). The Python import name is inkscape_mcp (underscore — PEP 8 / valid identifier). Both pip install inkscape-mcp and pip install inkscape_mcp resolve to the same project (PEP 503 name normalization).
Windows
The headless tools install and run exactly as above. The live bridge (inkscape_live) needs one extra piece: a Windows dbus-daemon, which isn't part of a stock Windows install. The simplest source is MSYS2 — install it, then:
pacman -S mingw-w64-x86_64-dbus # provides dbus-daemon.exe; MCP auto-discovers itgdbus.exe itself already ships with Inkscape, and the daemon's dependency DLLs are covered by Inkscape's, so MSYS2 is only the delivery vehicle for that one dbus-daemon.exe. If you already have one elsewhere, point INKSCAPE_MCP_DBUS_DAEMON at it (and INKSCAPE_MCP_GDBUS if gdbus.exe isn't found automatically).
On Windows the live bridge launches and manages its own Inkscape instance — a hand-launched Inkscape isn't on the bus, so have the agent open_file a document to work on it. Tested on Inkscape 1.4.x.
macOS
# Inkscape 1.4.x from inkscape.org in /Applications, then:
brew install dbus glib uv
git clone https://github.com/aravindev/inkscape_mcp.git
cd inkscape_mcp
uv sync
claude mcp add inkscape_mcp -s user -- uv run --directory "$PWD" inkscape_mcpThe live bridge launches and manages its own Inkscape; use open_file to work on a
document. See docs/INSTALL.md.
Configuration
The Claude Code entry the install command above creates looks like:
{
"mcpServers": {
"inkscape_mcp": {
"command": "uvx",
"args": ["inkscape_mcp"]
}
}
}Pin a non-default Inkscape with INKSCAPE_BIN=/path/to/inkscape in the server env; the server only falls back to searching $PATH when nothing pins it. Inspect from the agent via inkscape_system(operation="diagnostics") — its config_sources block reports each tracked setting's effective value alongside where it came from (env_var, config_file, cli_flag, auto_detected or default).
Try asking your agent to…
Editing the file you have open
"Recolor everything blue to red"
"Open document properties — I can't find the DPI setting"
"Select the pen tool so I can draw a curve"
"Show me the XML editor"
"Hide the snap controls bar"
"Add a drop shadow to all the rectangles"
"Convert this monogram to a single compound path"
"Run a boolean union on the two selected shapes"
Generating SVG content
"Drop in an isometric grid into this document"
"Generate a calendar for the current month and paste it here"
"Make me a 24×24 settings cog icon — currentColor stroke, round caps"
Inspection & format conversion
"Export this to a 4× PNG and a print-ready PDF"
"What's the bounding box of #logo-mark?"
"Optimize this SVG — strip Inkscape namespace cruft"
"List every object in the file with its type and size"
Live-canvas workflows (Inkscape running)
"Read what I have selected"
"Align these three icons horizontally with equal spacing"
"Swap the whole palette to a warmer earth-tone scheme"
"Add a 3-stop gradient to the rect with id
hero"
The agent picks the right tool. It can drive over 1,000 of Inkscape's actions over D-Bus (1,083 app-scope, 163 window-scope and 30 document-only actions such as undo on Inkscape 1.4.4 — ask for the exact figure with inkscape_live(operation="ping")), fall back to headless CLI when the GUI isn't running, and run inkex extensions for things D-Bus doesn't cover.
Available tools
inkscape_file— load, save, convert (PDF/PNG/EPS/PS/…), validate, batch convert.inkscape_vector— 49 ops covering boolean, tracing, path simplification, optimization, alignment, layer export, geometry mutation, barcodes, LPE chains, tile clones.inkscape_analysis— quality scoring, statistics, object lists, layer structure.inkscape_system— server status, diagnostics, extension discovery and execution.inkscape_extension— discover and invoke any installed inkex extension (headless or on the live canvas).inkscape_gradient— gradient-stop manipulation; linear↔radial conversion.inkscape_metadata— read/write Dublin-Core RDF metadata.inkscape_live— drive the running GUI over D-Bus: any Inkscape action (including undo/redo), XML edits,rasterizeso the agent can see the canvas (preserves undo).
Full operation list in docs/TOOLS.md.
How the agent learns to use it
An agent that just installed this server doesn't know your workflow, so the server teaches it. MCP's InitializeResult.instructions is pushed into the client's system prompt on connect, and this server uses it to establish the working method rather than just the mechanics: compose procedurally instead of hand-writing SVG (place primitives, then let Inkscape align, distribute, boolean and clone them), rasterize and actually look at the result before declaring it done, ask you to select the objects you want help with, and open the dialog or tool you're asking about instead of describing a menu path.
Deeper material is pull-based — resource://inkscape/mcp-workflow (operational guide, recipes, and the Inkscape rendering pitfalls that silently ruin output), resource://inkscape/cli-actions and resource://inkscape/gui-actions (the full action catalog), plus prompt://inkscape/design-workflow for the step-by-step design loop, which most clients surface as a slash command. The pushed instructions name those explicitly so the agent knows to fetch them.
Learn more
docs/INSTALL.md — full install walkthrough.
docs/TOOLS.md — every operation per tool.
docs/TROUBLESHOOTING.md — when things break.
src/inkscape_mcp/reference/ — captured Inkscape 1.4.4
--action-list, the GUI-only window/document actions, and--help; ships in the wheel and is served asresource://inkscape/cli-actions/gui-actions/cli-help.
Star history
Support
If you like my work and found this useful, feel free to support me at buymeacoffee.com/aravindev.
License
MIT — see LICENSE. This project is a fork of upstream MIT-licensed work; attribution and lineage details are in NOTICE.md.
Available Tools
8 toolsinkscape_analysisInkscape AnalysisBRead-onlyIdempotent
INKSCAPE_ANALYSIS — Inspect SVG structure, stats, quality, and dimensions (read-only).
PORTMANTEAU RATIONALE: Analysis calls are grouped so agents can validate before mutating.
Operations: quality, statistics, validate, objects, dimensions, structure.
Inputs: operation (required), input_path (required). Returns: object
inkscape_extensionInkscape ExtensionCDestructive
Discover and invoke any installed Inkscape extension with custom params.
Inputs: operation (required), params, target, input_path, +2 more. Returns: object
inkscape_fileInkscape FileADestructive
INKSCAPE_FILE — Load, convert, export, and validate SVG/other files via Inkscape CLI.
PORTMANTEAU RATIONALE: One tool keeps file I/O discoverable without dozens of
single-purpose tools; operation selects the CLI behavior.
Operations:
load: Read/validate path exists for editing workflows.
save: Persist changes (requires paths per server policy).
convert: Export to pdf/png/etc. (needs output_path, format).
info: Metadata and dimensions.
validate: Structural check via CLI query.
list_formats: Bounded list of supported export formats (no disk read required).
Inputs: operation (required), latex, format, margin, +11 more. Returns: object
inkscape_gradientInkscape GradientADestructive
Add/remove/recolor gradient stops; convert linear↔radial (headless — edits a file).
Preferred over hand-writing gradient SVG for file/headless work. NOT a live tool:
it reads/writes a file, so for gradients on an OPEN document use inkscape_live
edit_xml instead (avoids a reopen).
Inputs: operation (required), input_path (required), output_path (required), stop_color, +3 more. Returns: object
inkscape_liveInkscape LiveADestructive
Drive the RUNNING Inkscape GUI — the user's already-open document — live over D-Bus.
Work on the open document IN PLACE; do not recreate it. Prefer Inkscape's own
live tools over hand-writing SVG: use apply_action for actions (it finds the
app, window or document scope itself, so undo/redo work too) and
inkscape_extension run_live WITH NO PARAMS for filters/effects like drop
shadow and blur — select the target first, then call it; that is the only
run_live mode that sees the live document and selection. (Passing params
renders on an empty canvas and suits generator extensions only.)
(The inkscape_gradient tool is headless/file-based — not for the live doc.)
Use edit_xml (raw-SVG set_attr/append/insert_*/remove/replace, targeted by
XPath, multi-node capable) for everything else, e.g. editing gradients on the
live doc — it is the reliable persisting edit path. execute_inkex does NOT
persist mutations; don't use it to edit.
Every op acts on Inkscape's ACTIVE document and reports which one that was in
data.active_document. window_id cannot route — Inkscape 1.4 has no
focus-window action — so it is an assertion: leave it at 0 to accept the active
document, or pass a window number to have the call REFUSE when more than one
document is open and the target is therefore ambiguous. Check
active_document before any destructive edit; auto-save writes to disk.
Operations: ping, get_document_xml, get_selection, set_selection, insert_svg, delete_selected, apply_action, list_actions, open_file, save_snapshot, edit_xml, path_edit, path_offset, inspect_selection/layers/defs/view/pages/element, execute_inkex, rasterize.
Inputs: operation (required), target, payload, window_id. Returns: object
inkscape_metadataInkscape MetadataBIdempotent
Read/write Dublin-Core metadata in the SVG's rdf:RDF block.
Inputs: operation (required), input_path (required), value, output_path. Returns: object
inkscape_systemInkscape SystemCIdempotent
INKSCAPE_SYSTEM — Server/Inkscape status, help, diagnostics, version, extensions.
PORTMANTEAU RATIONALE: Operational and introspection calls stay in one discoverable tool.
Operations: status, help, diagnostics, version, config, list_extensions, execute_extension.
Inputs: operation (required), input_file, output_file, extension_id, +1 more. Returns: object
inkscape_vectorInkscape VectorCDestructive
INKSCAPE_VECTOR — Vector editing, booleans, trace, QR/barcode, path ops, previews.
PORTMANTEAU RATIONALE: Inkscape exposes many CLI actions; grouping avoids tool explosion.
Operations include: trace_image, generate_barcode_qr, apply_boolean, path_simplify, optimize_svg, scour_svg, render_preview, query_document, measure_object, export_dxf, layers_to_files, object_raise/lower, set_document_units, and others (see Literal).
Inputs: operation (required), x, y, dpi, +29 more. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 8 tools
The live-vs-headless split is explicitly documented, which helps, but several tool pairs still overlap: validate appears in both inkscape_file and inkscape_analysis, dimensions/object inspection is spread across inkscape_analysis, inkscape_vector (query_document/measure_object) and inkscape_live (inspect_*), and export/convert is split between inkscape_file and inkscape_vector (render_preview/export_dxf). Most confusingly, inkscape_extension (discover/invoke extensions) competes with inkscape_system's list_extensions/execute_extension with no guidance on which to use. An agent must read carefully to avoid misselection.
All tools follow a clean inkscape_<category> namespace (live, extension, file, vector, analysis, system, gradient, metadata) with no mixing of camelCase or verb styles. Minor deviation: the categories mix adjectives ('live') and nouns, and are abstract buckets rather than action names, so the name alone doesn't reveal the operations. Still highly consistent and predictable.
Eight portmanteau tools is a well-scoped surface for a rich GUI+CLI domain and avoids the tool explosion that single-purpose wrapping would create. The tradeoff is that several tools hide long operation lists (inkscape_live, inkscape_vector) whose contents must be discovered from descriptions rather than names.
Coverage is broad: file load/save/convert/validate, vector ops and booleans, live document editing, analysis, gradients, metadata, extensions, and system introspection. Gaps remain around shape/text primitives (no dedicated rect/circle/text creation) and explicit layer management beyond layers_to_files, but core SVG edit lifecycle is covered.
Maintenance
Related MCP Connectors
Make games with AI: one MCP server that connects your agent to Unity, Unreal and Godot editors.
MCP server for progressive tool usage at any scale (see https://klavis.ai)
MCP server for Hailuo (MiniMax) AI video generation
Official MCP server for Agentwork — delegate tasks to AI agents with human-in-the-loop
Related MCP Servers
- AlicenseAqualityDmaintenanceA minimal MCP server for AI-driven canvas manipulation and visualization using tldraw. It enables AI clients to programmatically create, update, and manage shapes, flowcharts, and frames on a live interactive canvas.92MIT
- AlicenseAqualityCmaintenanceMCP server that turns AI into an SVG artist. One rendering engine with a rich JSON schema, AI controls all design parameters. Renders animated SVGs with CSS @keyframes and SMIL animations. Supports 16+ element types, parametric curves, pattern groups, gradient/filter/clip/mask definitions, and PNG preview. No external dependencies, runs locally via npx.3127 npm31MIT
- AlicenseNot gradedqualityBmaintenanceEnables AI agents to control Inkscape for vector graphics editing via MCP tools.102MIT
- FlicenseNot gradedqualityDmaintenanceAn MCP server that lets AI assistants control Adobe Illustrator locally—running ExtendScript, capturing canvas screenshots, exporting artwork, and optionally remembering techniques—all without network activity.-