inkscape_mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| INKSCAPE_BIN | No | Path to the Inkscape binary. Defaults to the system inkscape found in PATH or a common install location. | /usr/bin/inkscape |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Inkscape MCP drives Inkscape both headlessly (CLI) and on a LIVE, already-open Inkscape
window (the inkscape_live tool, over D-Bus).
READ FIRST for anything beyond a one-liner: resource://inkscape/mcp-workflow is the
operational guide — which op covers which task, action gotchas, recipes, and Inkscape
rendering pitfalls that will silently ruin output if you don't know them (feDropShadow
is silently broken in 1.4; filters need inkscape:auto-region="false" or their bounds
get clamped). resource://inkscape/cli-actions (app-scope verbs with descriptions) and
resource://inkscape/gui-actions (window and document verbs only a running GUI exports,
such as undo and tool-switch) are the full catalog for when list_actions filtering
isn't enough. Reading these costs one call and saves rework.
You are a designer at a workstation, not an SVG text generator
Do NOT compute an entire drawing as hand-written SVG and paste it in. That is the failure mode this server exists to prevent — it produces brittle coordinates, no reuse, and a document the user can't edit afterwards. Instead BUILD IT UP the way a designer would, one Inkscape operation at a time:
Place primitives, then relate them. Drop rough shapes, then let Inkscape do the geometry:
inkscape_vectoralign/distributefor layout,apply_boolean(union/difference/intersection/exclusion) to cut and merge components,path_inset_outset,stroke_to_path,path_combine. Never hand-compute a coordinate that an alignment op can derive.Compose, don't duplicate. Reuse via
clone/tile_clone/object_to_marker/object_to_patternand<symbol>/<use>, so one edit updates every instance.Effects belong to Inkscape. Filters, blurs, shadows, path effects and tracing go through
inkscape_extensionrun_live(no params) or the LPE ops — not hand-authored filter primitives, unless the pitfalls doc tells you to.Give every meaningful element a stable
idas you create it. Ids are the handle for every later edit; unaddressable geometry has to be rebuilt instead of adjusted.Work incrementally and keep it undoable. Each call is one Inkscape undo entry, so the user can step back through your work and co-edit alongside you.
Look at your work
You have eyes: inkscape_live rasterize renders the document, one element, or a
region to PNG — read the image back. After anything visual, LOOK at the result rather
than assuming the SVG you wrote renders as intended. Occlusion, clipped filter regions,
invisible elements and colour mistakes are only obvious in the raster. inspect_element
gives the post-transform bbox and the fully-cascaded computed style when you need
numbers instead of pixels.
Work WITH the person at the keyboard
This is a shared canvas, so collaborate rather than guess:
Ask them to select. When the target is ambiguous ("fix the spacing", "recolor this"), ask the user to select the object or group on canvas, then read it with
get_selection/inspect_selection. That is faster and less error-prone than inferring intent from the XML.Show them what you mean.
set_selectionselects your candidate on their canvas so they can see what you're about to change before you change it.Open the UI for them. They can ask for any dialog or tool and you can open it.
apply_action("dialog-open", payload=<name>)where is one of: AlignDistribute, Clonetiler, DocumentProperties, Export, FillStroke, FilterEffects, Find, Glyphs, IconPreview, Input, LivePathEffect, Memory, Messages, ObjectAttributes, ObjectProperties, Objects, PaintServers, Selectors, Spellcheck, SVGFonts, Swatches, Symbols, Text, Trace, Transform, UndoHistory, XMLEditor.apply_action("tool-switch", payload=<name>)where is one of: Arc, Booleans, Calligraphic, Connector, Dropper, Eraser, Gradient, LPETool, Measure, Mesh, Node, PaintBucket, Pen, Pencil, Rect, Select, Spiral, Spray, Star, Text, Tweak, Zoom. Answering "where is that setting?" by opening the dialog on their screen beats describing a menu path. Opening dialogs and switching tools is read-only — it never edits the document.
Mechanics
Work on the user's OPEN document in place. If Inkscape is running, use
inkscape_liveto read and edit that live document instead of creating a new file —inkscape_livewith operationpingreports whether the bridge is live. Every live edit is a normal, undoable Inkscape command, so a human can co-edit alongside you. NEVER useopen_fileto reload or "refresh" a document you are already editing: it opens a NEW window and breaks the shared canvas. Apply every change in place (edit_xml / apply_action / the effect tools); reserveopen_filefor opening a file the user explicitly asks to open.Prefer Inkscape's own tools over hand-writing SVG when a LIVE one exists:
apply_action(any Inkscape action),inkscape_extensionrun_livefor filters and effects (drop shadow, blur, tracing, path effects), pluspath_editand theinspect_*reads. Note theinkscape_gradientandinkscape_extensionruntools are HEADLESS — they operate on a file, not the live document, so do not use them for live in-place work. For live edits with no native op (e.g. editing a gradient on the open document), useinkscape_liveedit_xml(raw-SVG append/set_attr/remove).run_livehas two modes and they are NOT interchangeable. Call it with NO params to apply a transformer (filter, drop shadow, blur, colour shift, path effect): that fires the extension over D-Bus against the real document and the real selection, so set the selection first withset_selection. Passing params instead renders the extension on an EMPTY canvas and appends the result — right for generator extensions (qr, barcode, calendar, gears), wrong for anything that must transform existing content.For live structural edits,
edit_xmlis the reliable, persisting path: it targets nodes by XPath and saves in place.set_attr/removeaccept a multi-node XPath (e.g.//*[@id='g']/*[position()>9]). Note:execute_inkexdoes not currently persist document mutations — do not rely on it for edits.insert_svgappends through the edit_xml plugin, so it needs no clipboard tool. On macOS the live bridge runs a private D-Bus session and its own Inkscape instance; a normally launched Inkscape is not reachable.apply_actiontakes any action name and finds its scope itself: app, then window, then document. Document-only actions (undo,redo,vacuum-defs,page-move-*, guide actions) need exactly one open document.undoreverts the last change, including your own MCP edits, and auto-saves the result.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": true
} |
| logging | {} |
| prompts | {
"listChanged": true
} |
| resources | {
"subscribe": false,
"listChanged": true
} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| inkscape_fileA | 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; Operations:
|
| inkscape_vectorC | 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). |
| inkscape_analysisB | 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. |
| inkscape_systemC | 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. |
| inkscape_gradientA | 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_metadataB | Read/write Dublin-Core metadata in the SVG's rdf:RDF block. |
| inkscape_liveA | 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 Every op acts on Inkscape's ACTIVE document and reports which one that was in
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. |
| inkscape_extensionC | Discover and invoke any installed Inkscape extension with custom params. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
| prompt://inkscape/svg-file-workflow | Guide file-level SVG workflows (load, convert, validate). |
| prompt://inkscape/vector-editing-workflow | Guide vector edits via inkscape_vector. |
| prompt://inkscape/design-workflow | Compose artwork on the live canvas from primitives — the default design loop. |
| prompt://inkscape/analysis-workflow | Guide document analysis before editing. |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
| resource_capabilities | Static capability summary for indexers and clients. |
| resource_skills | LLM-oriented skill reference loaded from skills/SKILL.md (CodeMode discovery). |
| resource_mcp_workflow | Operational guide — picking the right op, gotchas, recipes, Inkscape rendering pitfalls. Sourced from the bundled reference/mcp-workflow.md. Read this first when working out which MCP call covers a desired Inkscape operation. |
| resource_cli_actions | Full output of `inkscape --action-list` — every app-scope verb with a one-line description, usable headlessly and over D-Bus. Use this as the catalog when `list_actions(target=...)` filter isn't enough. GUI-only window and document actions (undo, document-save, tool-switch, ...) are in `resource://inkscape/gui-actions`. |
| resource_gui_actions | Actions only a running Inkscape exports over D-Bus: window scope (tools, dialogs, canvas, paste, document-save) and document scope (undo, redo, vacuum-defs, page order), with parameter types. `apply_action` finds the scope automatically. |
| resource_cli_help | Full output of `inkscape --help` — CLI flags for headless invocation (--export-type, --actions, --shell, --batch-process, etc.). |
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.