Ink/Stitch MCP Bridge
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@Ink/Stitch MCP Bridge Convert logo.svg to DST with 0.5mm satin stitches"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
Ink/Stitch MCP Bridge
An MCP server that gives AI assistants full headless access to Ink/Stitch machine-embroidery tooling — no Inkscape installation required.
SVG designs go in; stitch-ready machine files (DST, PES, JEF, EXP, VP3, and ~17 more), PNG previews, validation reports, and digitized lettering come out.

The image above is the bridge's own output: generate_lettering("Hello", "Amitaclo") →
machine-ready DST → render_png_preview.
MCP client (Claude Code / Claude Desktop)
│ stdio (JSON-RPC)
▼
inkstitch-mcp server (FastMCP, this package)
├── native tools ──────────► pystitch + lxml (stats, PNG render, format
│ conversion, param editing, font/format lists)
└── subprocess tools ──────► .venv-inkstitch python
vendor/inkstitch/inkstitch.py --extension=…
(export, import, lettering, validation,
stitch-plan previews, transforms)Tools (21)
Tool | What it does |
| Verify toolchain; optional end-to-end smoke export |
| Machine formats Ink/Stitch reads (~50) and writes (~22) |
| 140 bundled digitized lettering fonts |
| All legal per-element stitch parameters (~136) |
| Inventory an SVG: ids, labels, stitch type (fill/stroke/satin), params |
| Read/write |
| SVG → machine file (format from output extension) + stitch stats |
| Machine file → editable stitch-plan SVG |
| One SVG → many formats in a ZIP, optional panelization |
| Stitch/jump/trim/color counts, threads, size (mm) of a machine file |
| Machine file → machine file (e.g. DST → PES) |
| PNG image of the stitches (from machine file or SVG) |
| Plain-text thread/color report |
| Structured validation: errors/warnings with positions & fixes |
| Stitch-density heat-map layer (thread-break risk) |
| Render the actual stitch plan into an SVG layer |
| Remove problem-causing tiny objects (dry-run by default) |
| stroke_to_satin, auto_satin, auto_run, fill_to_stroke, jump_to_stroke, break_apart, outline |
| Strip embroidery params/commands from an SVG |
| Text → embroidered lettering in any bundled font |
Related MCP server: SVGator MCP Server
Setup
Requires Python 3.11 (Ink/Stitch's pinned dependencies do not support newer interpreters) and git. Developed and tested on Windows 11; the code paths are OS-aware but only Windows has been exercised.
# --recursive pulls the Ink/Stitch submodule AND its fonts submodule (140 fonts)
git clone --recursive https://github.com/GreerBK/InkStitchMCP
cd InkStitchMCP
py -3.11 -m venv .venv-inkstitch
# inkex's repo has a test file exceeding Windows path limits; scope the fix to this install:
set GIT_CONFIG_COUNT=1&& set GIT_CONFIG_KEY_0=core.longpaths&& set GIT_CONFIG_VALUE_0=true
.venv-inkstitch\Scripts\python -m pip install -r requirements-inkstitch.txt
.venv-inkstitch\Scripts\python -m pip install -e .If you cloned without --recursive: git submodule update --init --recursive.
Verify everything with the health_check tool (or run the test suites below).
Paths are overridable via INKSTITCH_MCP_ROOT / INKSTITCH_MCP_REPO /
INKSTITCH_MCP_PYTHON / INKSTITCH_MCP_OUTPUT (see src/inkstitch_mcp/config.py),
plus INKSTITCH_MCP_TIMEOUT / INKSTITCH_MCP_SLOW_TIMEOUT (seconds) and
INKSTITCH_MCP_TRACE=1 for stderr tracing of subprocess calls.
Registering with a client
Claude Code — either copy .mcp.json.example to .mcp.json (auto-loads for this
project) and fill in your path, or register globally:
claude mcp add inkstitch -- <path-to-InkStitchMCP>\.venv-inkstitch\Scripts\python.exe -m inkstitch_mcpClaude Desktop — add to %APPDATA%\Claude\claude_desktop_config.json:
{
"mcpServers": {
"inkstitch": {
"command": "<path-to-InkStitchMCP>\\.venv-inkstitch\\Scripts\\python.exe",
"args": ["-m", "inkstitch_mcp"]
}
}
}Tests
.venv-inkstitch\Scripts\python tests\e2e.py # 34 checks, every tool, real designs
.venv-inkstitch\Scripts\python tests\protocol_smoke.py # real MCP stdio round-tripDesign notes (hard-won)
These are the traps this bridge encodes; they matter if you modify runner.py:
Exit codes lie. Ink/Stitch exits 0 for parse errors, "no embroiderable elements", and domain errors — with the explanation on stderr and an empty payload. Success is judged per-tool from payload presence, never from the return code.
stdout is binary. Embroidery/ZIP payloads come over stdout (the Inkscape convention); the
outputextension switches stdout toO_BINARYon Windows. Always capture bytes; stderr is UTF-8, flushed once at process exit.stdin=DEVNULLis load-bearing. Under an MCP client, the server's stdin is the live JSON-RPC pipe; letting a child inherit it deadlocks the child interpreter at startup on Windows (diagnosed via py-spy: zero CPU, no Python frames).Legacy SVGs summon an invisible dialog. Every extension's
load()runs the version migrator with a blocking wx prompt for unversioned files containing Ink/Stitch attributes — including--extension=update_svgitself. The preflight inrunner.pydetects the condition (same XPath aslib/update.py) and migrates via_migrate_helper.py, which calls the migrator directly with the prompt disabled.Never expose raster preview modes.
png_realistic,png_simple, realistic-DPI stitch plans, and the ZIP--format-png-realistic/simpleflags all shell out to aninkscapebinary. PNG previews here use pystitch's native renderer instead.The
outputextension's parser is hand-rolled. Options must be single--name=valuetokens,--formatis mandatory, values containing=crash it, and--outputis swallowed (hence stdout capture there,--output=<tmpfile>elsewhere).Arg spelling is per-extension. Some use hyphens, some underscores, some both (
batch_letteringmixes them in one parser). Flags are hardcoded per tool from the vendored argparsers — don't "normalize" them.--del_paramsmust always be passed toremove_embroidery_settings: its argparse default is the Python boolTruewithtype=str, which crashes when omitted.batch_letteringdumps the input SVG on validation failure with exit 0 — the ZIP magic (PK) check is what actually detects failure.Documents parameterized by this bridge are version-stamped.
set_element_paramswrites the currentinkstitch_svg_versionmetadata; without it, the next tool call would run the v0→v4 legacy migration on freshly written modern params and silently change their meaning (e.g. solid strokes forced tozigzag_stitch).Slow tools run off the event loop. Subprocess-backed tools are registered via
blocking_tool(async +anyio.to_thread); registering them as plain sync tools freezes all MCP traffic for the duration of an export.custom_file_nameis a path fragment inside the zip extension — it is validated against a strict character allowlist to prevent writing outside the target directory.
License
This bridge code: MIT (see LICENSE). Ink/Stitch is referenced as a git submodule —
not distributed in this repository — and is GPL-3.0-or-later; pystitch and other
dependencies carry their own licenses. If you distribute a bundle that includes the
vendor/inkstitch checkout, GPL terms apply to that component.
Available Tools
21 toolscleanup_documentB
Remove tiny/empty objects that would cause thread breaks. dry_run=True (default) only reports what would be removed.
Inputs: svg_path (required), dry_run, remove_fills, remove_satins, +6 more.
convert_machine_formatB
Convert one machine embroidery file to another format directly (e.g. mydesign.dst -> mydesign.pes). Format taken from the output extension.
Inputs: input_path (required), output_path (required).
density_mapC
Annotate an SVG with a stitch-density heat map layer (red/yellow/green markers per stitch).
Inputs: svg_path (required), indicator_size, output_svg_path, num_neighbors_red, +3 more.
design_statsB
Stitch statistics for a machine embroidery file: stitch/jump/trim counts, color changes, threads, size in mm.
Inputs: file_path (required).
export_embroideryA
Compile an SVG design into a machine embroidery file (format from the output extension: .dst, .pes, .jef, .exp, .vp3, ...). Returns stitch statistics.
Defaults to <output_dir>/.dst when output_path is omitted.
Inputs: svg_path (required), laser_mode, output_path.
export_zipA
Export an SVG design to several formats at once as a ZIP (e.g. ["dst","pes","svg","threadlist"]). x/y_repeats panelize copies with the given spacing (mm).
Inputs: formats (required), svg_path (required), x_repeats, x_spacing, +4 more.
generate_letteringA
Create machine-embroidered text using Ink/Stitch's digitized fonts.
font is the font name from list_fonts (e.g. "Amitaclo"). formats defaults to ["dst", "svg"]. scale_percent is clamped to the font's supported range. NOTE: each newline-separated line of text becomes a SEPARATE design (own file set) — that is the batch semantics of the underlying extension. trim: off/line/word/glyph. color_sort: off/all/line/word. text_align: left/center/right/block/letterspacing. Extracted files land in output_dir (default: <output_dir>/lettering_).
Inputs: font (required), text (required), trim, formats, +7 more.
get_element_paramsC
Read Ink/Stitch parameters from SVG elements (all parameterized elements, or only the given ids).
Inputs: svg_path (required), ids.
health_checkA
Verify the Ink/Stitch toolchain is ready (venv, checkout, fonts, pystitch).
With run_smoke_test=True, also exports a tiny test design to DST end-to-end (takes a few seconds).
Inputs: run_smoke_test.
import_embroideryA
Convert a machine embroidery file (dst/pes/jef/exp/vp3/hus/...) into an SVG of its stitch plan, editable in Inkscape.
Inputs: file_path (required), output_svg_path.
list_elementsB
Inventory embroiderable elements in an SVG: ids, labels, inferred stitch type (fill/stroke/satin), and existing Ink/Stitch params.
Inputs: svg_path (required).
list_fontsA
List embroidery lettering fonts available to generate_lettering (name, scale limits, description).
Inputs: no named parameters.
list_formatsA
List machine-embroidery file formats Ink/Stitch can read and write (dst, pes, jef, exp, vp3, ...).
Inputs: no named parameters.
list_known_paramsA
List every legal Ink/Stitch per-element parameter name usable with set_element_params.
Inputs: no named parameters.
preview_stitch_planC
Add a rendered stitch-plan layer to an SVG (what will actually be sewn). mode: 'simple' or 'realistic-vector'.
Inputs: svg_path (required), mode, render_jumps, needle_points, +2 more.
remove_embroidery_settingsC
Strip Ink/Stitch parameters and/or command symbols from an SVG, returning it to a plain vector design.
Inputs: svg_path (required), remove_params, output_svg_path, remove_commands, +1 more.
render_png_previewA
Render a PNG preview of a design's stitches. Accepts a machine file (dst/pes/...) or an SVG (which is compiled first). Returns the image.
Inputs: file_path (required), output_png_path.
set_element_paramsA
Set or remove Ink/Stitch stitch parameters on SVG elements.
updates maps element id -> {param_name: value}; value null removes the param. Param names must come from list_known_params (e.g. angle, row_spacing_mm, running_stitch_length_mm, satin_column, fill_underlay). Booleans are written as true/false; *_mm values are millimeters. Overwrites the input SVG unless output_svg_path is given.
Inputs: updates (required), svg_path (required), output_svg_path.
thread_listB
Plain-text thread/color report for an SVG design: design size, stitch counts, thread order.
Inputs: svg_path (required). Returns: result
transform_elementsB
Apply an Ink/Stitch conversion to SVG elements and save the result.
operation: stroke_to_satin (center-line pair -> satin column), auto_satin (route satins optimally), auto_run (route strokes into one running stitch), fill_to_stroke (fill -> centerline), jump_to_stroke (connect jumps with strokes, whole document), break_apart (split multi-part fill paths), outline (fill -> outline stroke). ids selects target elements (required for all but jump_to_stroke; get them from list_elements). options overrides operation-specific flags, e.g. {"threshold_mm": 5}.
Inputs: svg_path (required), operation (required), ids, options, +1 more.
troubleshootB
Validate a design's embroidery elements; returns structured errors/warnings with positions and suggested fixes.
Inputs: svg_path (required), show_errors, show_warnings, show_type_warnings.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 21 tools
Each tool targets a distinct operation: import, list resources, health check, export, transform, validate, generate lettering, etc. No two tools have overlapping purposes; even similar tools like preview_stitch_plan and render_png_preview are clearly differentiated by output (SVG layer vs PNG image).
All tool names follow a consistent snake_case verb_noun or verb_noun_noun pattern, with clear action and target. Examples: import_embroidery, list_fonts, set_element_params, etc. No mix of conventions.
With 21 tools, the server covers a broad range of embroidery design workflows. While slightly above the typical 3-15 range, each tool serves a distinct purpose and the count feels justified for the domain.
The tool set covers the full lifecycle of embroidery design: importing, inspecting, modifying, generating, validating, previewing, exporting, and housekeeping. Obvious gaps like creating elements from scratch are handled by the SVG-first workflow.
Maintenance
Related MCP Connectors
Convert any image into machine embroidery files (DST, PES…) or vector graphics (SVG, PDF, EPS, DXF).
Lets AI assistants draw: logos, posters, illustrations and scenes, as editable SVG and PNG.
Create professional SVG artwork, icons and vector logos from a prompt, or vectorize any image.
Convert PNG, JPG and WebP images, including AI-generated ones, to clean SVG, PDF, EPS or DXF.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI agents to vectorize raster images and import vector files (PDF/AI/EPS), then inspect, edit, render, and optimize SVGs locally.6MIT

SVGator MCP Serverofficial
FlicenseNot gradedqualityCmaintenanceEnables AI assistants to browse, inspect, edit, create, and export SVGator projects, handling everything from simple color edits to complex animated exports.5-- AlicenseNot gradedqualityDmaintenanceEnables AI agents to create, inspect, validate, and export SVG designs using Inkscape CLI through MCP tools.2Apache 2.0
- FlicenseNot gradedqualityCmaintenanceEnables ChatGPT to queue validated embroidery designs, compile constrained one-color designs, describe Brother SE700 limits, list queued jobs, and request phone-side transfers to a Brother SE700 after explicit user approval.-