Inkscape MCP

Give an MCP agent a working SVG toolbox and access to your open Inkscape drawing.

Inkscape MCP connects Inkscape to MCP clients through FastMCP. Create SVG from XML, edit paths, inspect documents, export previews, and insert editable artwork into the desktop document you are already working on. Ordinary drawing and export operations do not require a separate language model service.

Install · Tool reference · Examples · Configuration · Contribute

What works where

Tested environment: Ubuntu 26.04.1 LTS, Python 3.12.14, Inkscape 1.4.4. The test desktop runs GNOME Wayland. Desktop checks and file-based runtime checks exercise separate integration paths. The test suite also passes with Python 3.13.15 and Inkscape 1.4.3 in a clean Ubuntu 26.04 container. That container runs the two-window acceptance test under Xvfb with Python 3.12. Windows and macOS have CLI support; the live extension bridge targets Linux. See installation for platform details and native dependencies.

Related MCP server: inkscape-mcp

Quick start on Ubuntu

Install uv, then:

sudo apt update
sudo apt install inkscape git build-essential pkg-config python3-dev \
  libcairo2-dev libgirepository-2.0-dev gir1.2-gtk-3.0 \
  libmagic1t64 libglib2.0-bin python3-numpy python3-lxml python3-scour \
  python3-cssselect python3-platformdirs

git clone https://github.com/GianluDeveloper/inkscape-mcp.git
cd inkscape-mcp
uv sync --python 3.12
inkscape --version
uv run inkscape-mcp --help

The GTK/Cairo build packages are needed by inkex and its Python dependencies; installing Inkscape alone may not be enough for uv sync. The system Python packages are also required: Inkscape runs native extensions with its own interpreter, independently of the server's uv environment.

Configure a local MCP client using its server configuration format. A client that accepts mcpServers can use:

{
  "mcpServers": {
    "inkscape-mcp": {
      "command": "uv",
      "args": [
        "--directory", "/absolute/path/to/inkscape-mcp",
        "run", "inkscape-mcp", "--mode", "stdio"
      ]
    }
  }
}

Use an absolute path to uv too if your client cannot find it. Restart the MCP connection after installation or code updates, then call inkscape_system with {"operation":"status"}. Check data.inkscape.available in the response.

Draw in the open Inkscape document

Run the MCP server in the same logged-in desktop session as Inkscape. Install the bundled native extension once by calling inkscape_system with:

{"operation": "install_live_extension"}

Restart any Inkscape windows that were already open so they load the extension. Then, with one window in the ordinary desktop instance, call:

{"operation": "draw_test", "session_id": "desktop", "text": "Prova MCP OK"}

A blue rounded rectangle and editable text are inserted into the existing drawing. The server reads live SVG before and after the effect, checks the inserted objects, and returns their IDs with data.verified: true. Existing objects and Inkscape's undo history are preserved; Edit → Undo removes the insertion. The native effect uses SVG coordinates and does not take over the clipboard.

This is a real Inkscape export from the two-document desktop acceptance test. The editable SVG is included with the examples.

Use {"operation":"active_document","session_id":"desktop"} to inspect the current SVG, including unsaved edits. For your own artwork, call insert_svg with a complete svg_content document and the target session_id.

To save changes in that window to its current SVG filename, call inkscape_system:

{"operation": "save_document", "session_id": "desktop"}

The server verifies the saved content and returns data.verified: true and data.live_document_saved: true. It uses Inkscape's current filename, including changes made with File → Save As. For an unnamed drawing, use Save As in Inkscape first, or start a named drawing with new_document.

Work with several documents

Use new_document with a new output_path, or open_document with an existing SVG input_path. Each opens an independently addressed Inkscape instance and returns a session_id. Pass that ID to subsequent inspection, drawing, saving, and closing operations; keyboard focus does not choose the target.

{"operation": "new_document", "output_path": "/absolute/path/to/drawing.svg"}

list_documents discovers live sessions. save_document saves either a managed document or the single-window desktop to its current filename. An output_path different from that filename is rejected before saving; change the filename through Inkscape's Save As dialog. save_copy writes live content to another output_path while keeping the GUI filename; pending changes in the open document still need to be saved. close_document requests a normal close of a managed session and preserves Inkscape's unsaved-changes dialog.

See the multi-document procedure for complete requests. An ordinary desktop instance with several windows is ambiguous; use managed sessions for separate drawings. If an edit cannot be verified, inspect its target before retrying. Troubleshooting covers extension loading and session access.

Create and export a file

Call inkscape_vector:

{
  "operation": "construct_svg",
  "output_path": "/absolute/path/to/demo.svg",
  "svg_content": "<svg xmlns=\"http://www.w3.org/2000/svg\" width=\"160\" height=\"80\" viewBox=\"0 0 160 80\"><rect x=\"10\" y=\"10\" width=\"140\" height=\"60\" rx=\"12\" fill=\"#2878cc\"/></svg>"
}

Then call inkscape_file:

{
  "operation": "convert",
  "input_path": "/absolute/path/to/demo.svg",
  "output_path": "/absolute/path/to/demo.png",
  "format": "png"
}

Managed CLI exports validate the produced artifact before replacing the destination. Failed commands, timeouts, and cancellation preserve an existing destination. File operations work on the supplied paths; live drawing operations work on the open desktop document. See examples for previews, boolean operations, and a repeatable live drawing check.

HTTP and the optional dashboard

uv run inkscape-mcp --mode http --host 127.0.0.1 --port 11028

Connect an HTTP MCP client to http://127.0.0.1:11028/mcp. For the optional web interface, run in a second terminal:

cd web_sota
bun install --frozen-lockfile
bun run dev

Open http://127.0.0.1:11029. The frontend proxies to port 11028; the standalone CLI HTTP default is 11027. --mode dual is retained as an HTTP alias and does not start a second stdio listener.

Scope and current limits

The tool reference lists the registered MCP interface and marks incomplete operations. Some Python/REST capabilities, including layer and animation helpers, are not standalone MCP tools. External asset handoffs require the corresponding services. Sampling tools require client support for sampling.tools; workflow planning tools return plans, which the caller must execute through the editing tools.

This server can read and write local files and send commands to Inkscape. HTTP binds to loopback by default; use it within a trusted local environment. Detailed configuration and directory restrictions are described in Configuration.

Development and project history

uv sync --group dev
uv run pytest

See Development for focused tests, real Inkscape checks, formatting, and the repository layout. Contributions should include a reproducible problem or a working example, appropriate tests, and updated tool documentation. See CONTRIBUTING.md.

Credits

• sandraschi/inkscape-mcp is the base project continued by this repository. Its server, tooling, and original MIT attribution are retained.

• aravindev/inkscape_mcp informed the native live-editing extension and document/session design. Adapted components retain their upstream attribution; action discovery is independently implemented.

See Upstream integration for the reviewed revision and implementation boundaries. Attribution is recorded in NOTICE.md. Distributed under the MIT license. Report reproducible problems in GitHub Issues.