Inkscape MCP Server

A Model Context Protocol (MCP) server that enables live control of Inkscape through natural language instructions. This allows AI assistants like Claude to directly manipulate vector graphics in real-time.

Features

• 🎯 Live Instance Control - Direct manipulation of running Inkscape documents
• ⚡ D-Bus Integration - Real-time communication
• 🚀 Universal Element Creation - Create any SVG element with unified syntax
• 🏗️ Hierarchical Scene Management - Semantic organization with automatic ID collision handling
• 📐 Python Code Execution - Run arbitrary inkex code in live context
• 🖼️ Screenshot Support - Visual feedback with viewport capture

Platform Support

• ⚠️ Currently Linux Only - Uses D-Bus which is Linux-specific
• 🔮 Future: Cross-platform support possible via TCP sockets/named pipes

Quick Start

1. Installation (Linux Only)

1. Go to the Releases page
2. Download inkmcp-extension.zip from the latest release
3. Extract it to your Inkscape extensions directory:

   cd ~/.config/inkscape/extensions/
   unzip ~/Downloads/inkmcp-extension.zip

2. Make Scripts Executable

cd ~/.config/inkscape/extensions/inkmcp
chmod +x run_inkscape_mcp.sh inkmcpcli.py inkscape_mcp_server.py main.py

3. Start Inkscape

Launch Inkscape normally - the extension is hidden from the menu and only accessible via D-Bus.

4. Connect with AI Tools

Auto-Setup: The first time an AI client connects, it will automatically:

• Create Python virtual environment in ~/.config/inkscape/extensions/inkmcp/venv/
• Install all required dependencies from requirements.txt
• Start the MCP server

No manual setup required!

Claude Code

Edit your Claude configuration file:

# ~/.claude/claude-config.json

{
  "mcpServers": {
    "inkscape": {
      "command": "/home/USERNAME/.config/inkscape/extensions/inkmcp/run_inkscape_mcp.sh"
    }
  }
}

Anthropic Claude Desktop

Update Claude desktop app settings:

{
  "mcpServers": {
    "inkscape": {
      "command": "/home/USERNAME/.config/inkscape/extensions/inkmcp/run_inkscape_mcp.sh"
    }
  }
}

Google Gemini/Codex

For Gemini, edit settings file:

# ~/.gemini/settings.json

{
  "mcpServers": {
    "inkscape-mcp": {
      "command": "/home/USERNAME/.config/inkscape/extensions/inkmcp/run_inkscape_mcp.sh"
    }
  }
}

For Codex, edit configuration:

# ~/.codex/config.toml

[mcp_servers.inkscape-mcp]
command = "/home/USERNAME/.config/inkscape/extensions/inkmcp/run_inkscape_mcp.sh"

Usage Examples

With AI Assistant (Claude Code/Gemini/etc) - Requires Running Inkscape

"In Inkscape, draw a smooth sine wave starting at the left edge in the middle of the document and apply power stroke path effect to it"
"In Inkscape, create a beautiful logo with a radial gradient circle and elegant typography"
"In Inkscape, draw a mathematical spiral using varying circle sizes with golden ratio"
"In Inkscape, create a house illustration with gable roof, wooden door, and flower garden"
"In Inkscape, design a data visualization chart with bars with hatch fill and labels using current document size"
"In Inkscape, export the current document as high-resolution PNG for presentation"

Available MCP Tools

inkscape_operation - Universal tool for all Inkscape operations:

• Create any SVG element (circle, rect, text, path, gradient, etc.)
• Execute Python/inkex code in live context
• Get document/selection information
• Export viewport screenshots
• Hierarchical element creation with groups
• Automatic ID collision handling

Hybrid Execution

Execute code seamlessly across multiple Python contexts with automatic variable sharing!

execute-hybrid CLI Command

Interleave local Python execution with Inkscape operations using magic comments:

# @local
import random
points = [(random.randint(10, 200), random.randint(10, 200)) for _ in range(5)]

# @inkscape
for x, y in points:
    circle = Circle()
    circle.set("cx", str(x))
    circle.set("cy", str(y))
    svg.append(circle)

Features:

• 🔄 Full bidirectional variable flow (Local ↔ Inkscape)
• 🎯 get_element_by_id() helper function for reliable element lookup
• ⚠️ Full error tracebacks with fail-fast behavior

Usage:

python inkmcpcli.py execute-hybrid -f script.py

Blender-Inkscape Addon

Transfer curves and data from Blender to Inkscape in real-time!

Installation:

1. Blender > Edit > Preferences > Add-ons > Install
2. Select blender_addon_inkscape_hybrid.py
3. Enable "Scripting: Inkscape Hybrid Execution"
4. Set INKMCP_CLI_PATH to /path/to/inkmcp/inkmcpcli.py

Usage:

# @local - Runs in Blender
import bpy
curve = bpy.context.object
segs = [list(pt.co[:2]) for spline in curve.data.splines 
        for pt in spline.bezier_points]

# @inkscape - Runs in Inkscape via D-Bus
for x, y in segs:
    circle = Circle()
    circle.set("cx", str(x * 100))
    svg.append(circle)

Run with: Text > Run Hybrid Code (or Ctrl+Shift+H)

Features:

• ✨ One-click execution from Blender text editor
• 🔄 Automatic variable serialization
• ⚠️ Helpful warnings for non-serializable Blender objects
• 🎨 Real-time bezier curve transfer to Inkscape

Example: blender_paste_example.py - Complete bezier curve visualization

Note: Blender objects (Vectors, etc.) must be converted to lists for JSON serialization.

See BLENDER_HYBRID_README.md for detailed documentation.

Technical Details

Architecture

• Extension: inkscape_mcp.py - Inkscape extension triggered via D-Bus
• MCP Server: inkscape_mcp_server.py - FastMCP server handling AI requests
• CLI Client: inkmcpcli.py - Direct command-line interface for testing
• Operations: inkmcpops/ - Modular operation handlers

Communication Flow

AI Assistant → MCP Server → CLI Client → D-Bus → Inkscape Extension → Live Document

Advanced Usage

Direct CLI Usage (For Testing/Development)

# In the inkmcp directory - bypasses AI assistant for direct control

# Basic shapes
python inkmcpcli.py circle "cx=100 cy=100 r=50 fill=red"
python inkmcpcli.py rect "x=0 y=0 width=200 height=100 stroke=blue"

# Gradients
python inkmcpcli.py linearGradient "x1=0 y1=0 x2=200 y2=200 stops='[[\"0%\",\"green\"],[\"50%\",\"yellow\"],[\"100%\",\"red\"]]'"

# Code execution
python inkmcpcli.py execute-code "code='circle = inkex.Circle(); circle.set(\"cx\", \"150\"); circle.set(\"cy\", \"100\"); circle.set(\"r\", \"25\"); svg.append(circle)'"

# Document info
python inkmcpcli.py get-info

# Selection info
python inkmcpcli.py get-selection

# Export screenshot
python inkmcpcli.py export-document-image "format=png max_size=800"

Arbitrary Code Execution

Execute any Python/inkex code in the live Inkscape context:

# Create complex shapes programmatically
code = '''
rect = Rectangle()
rect.set('x', '10')
rect.set('y', '20')
rect.set('width', '100')
rect.set('height', '50')
rect.set('style', 'fill:blue;stroke:red;stroke-width:2')
svg.append(rect)
'''

Troubleshooting

Common Issues

1. D-Bus not found: Ensure you're on Linux with D-Bus session running
2. Extension not triggered: Check Inkscape is running and extension is installed
3. Python environment: Ensure virtual environment is activated with dependencies
4. Permissions: Make sure scripts are executable (chmod +x *.sh *.py)

Debug Mode

# Check D-Bus connection
gdbus introspect --session --dest org.inkscape.Inkscape --object-path /org/inkscape/Inkscape

# Structured JSON output
python inkmcpcli.py get-info --parse-out --pretty

Development

Adding New Operations

1. Create new file in inkmcpops/
2. Implement execute(svg, params) function
3. Add corresponding MCP tool in inkscape_mcp_server.py

License

GPL-3.0