Inkmcp
Inkscape MCP Server - Control Inkscape through AI assistants via Model Context Protocol
Installation
npx inkmcpAsk AI about Inkmcp
Powered by Claude ยท Grounded in docs
I know everything about Inkmcp. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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)
- Go to the Releases page
- Download
inkmcp-extension.zipfrom the latest release - 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:
- Blender > Edit > Preferences > Add-ons > Install
- Select
blender_addon_inkscape_hybrid.py - Enable "Scripting: Inkscape Hybrid Execution"
- 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
- D-Bus not found: Ensure you're on Linux with D-Bus session running
- Extension not triggered: Check Inkscape is running and extension is installed
- Python environment: Ensure virtual environment is activated with dependencies
- 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
- Create new file in
inkmcpops/ - Implement
execute(svg, params)function - Add corresponding MCP tool in
inkscape_mcp_server.py
