Skip to main content
Glama

Server Configuration

Describes the environment variables required to run the server.

NameRequiredDescriptionDefault
INKSCAPE_BINNoPath 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_vector align / distribute for 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_pattern and <symbol>/<use>, so one edit updates every instance.

  • Effects belong to Inkscape. Filters, blurs, shadows, path effects and tracing go through inkscape_extension run_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 id as 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_selection selects 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

  1. Work on the user's OPEN document in place. If Inkscape is running, use inkscape_live to read and edit that live document instead of creating a new file — inkscape_live with operation ping reports whether the bridge is live. Every live edit is a normal, undoable Inkscape command, so a human can co-edit alongside you. NEVER use open_file to 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); reserve open_file for opening a file the user explicitly asks to open.

  2. Prefer Inkscape's own tools over hand-writing SVG when a LIVE one exists: apply_action (any Inkscape action), inkscape_extension run_live for filters and effects (drop shadow, blur, tracing, path effects), plus path_edit and the inspect_* reads. Note the inkscape_gradient and inkscape_extension run tools 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), use inkscape_live edit_xml (raw-SVG append/set_attr/remove).

    run_live has 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 with set_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.

  3. For live structural edits, edit_xml is the reliable, persisting path: it targets nodes by XPath and saves in place. set_attr/remove accept a multi-node XPath (e.g. //*[@id='g']/*[position()>9]). Note: execute_inkex does not currently persist document mutations — do not rely on it for edits.

  4. insert_svg appends 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.

  5. apply_action takes 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. undo reverts 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

CapabilityDetails
tools
{
  "listChanged": true
}
logging
{}
prompts
{
  "listChanged": true
}
resources
{
  "subscribe": false,
  "listChanged": true
}

Tools

Functions exposed to the LLM to take actions

NameDescription
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; 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).

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_live edit_xml instead (avoids a reopen).

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 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.

inkscape_extensionC

Discover and invoke any installed Inkscape extension with custom params.

Prompts

Interactive templates invoked by user choice

NameDescription
prompt://inkscape/svg-file-workflowGuide file-level SVG workflows (load, convert, validate).
prompt://inkscape/vector-editing-workflowGuide vector edits via inkscape_vector.
prompt://inkscape/design-workflowCompose artwork on the live canvas from primitives — the default design loop.
prompt://inkscape/analysis-workflowGuide document analysis before editing.

Resources

Contextual data attached and managed by the client

NameDescription
resource_capabilitiesStatic capability summary for indexers and clients.
resource_skillsLLM-oriented skill reference loaded from skills/SKILL.md (CodeMode discovery).
resource_mcp_workflowOperational 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_actionsFull 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_actionsActions 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_helpFull output of `inkscape --help` — CLI flags for headless invocation (--export-type, --actions, --shell, --batch-process, etc.).

TDQS

B3.3/5.0

Scored across 8 tools

Disambiguation3/5

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.

Naming Consistency4/5

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.

Tool Count4/5

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.

Completeness4/5

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

ActivityMaintained
ResponsivenessOutdated data