Embroidery MCP

AI-assisted embroidery digitizing with Inkscape, Ink/Stitch, and MCP.

Goal

Build an MCP server that helps Codex or Claude inspect and prepare artwork for embroidery workflows. The long-term workflow is:

1. Image cleanup
2. Background removal
3. Color reduction
4. Vectorization
5. SVG cleanup
6. Embroidery analysis
7. Stitch assignment
8. Preview generation
9. Embroidery file export

V1 supports two workflows:

• SVG workflow: provide an SVG and the MCP cleans it, analyzes it, generates Ink/Stitch previews, exports DST/PES files, and writes operator reports.
• Image workflow: provide a PNG/JPG and the MCP reduces colors, removes a simple corner-sampled background, creates a layered SVG by color, then runs the SVG operator workflow.

Current Scope

Implemented:

• Python project scaffold
• MCP stdio server
• validate_svg tool
• cleanup_svg tool
• simulate_design tool
• analyze_design tool
• check_environment tool
• generate_preview tool
• generate_stitch_plan tool
• export_embroidery tool
• create_operator_package tool
• vectorize_image tool
• create_image_operator_package tool
• SVG validation tests
• Example SVG and PNG files

Deferred:

• automatic stitch assignment
• advanced photo cleanup and tracing
• thread palette matching

Requirements

• Python 3.12+
• uv
• Git
• Inkscape
• Ink/Stitch
• Claude Desktop or Codex MCP configuration for MCP use

Verify local tools:

python --version
uv --version
git --version
/Applications/Inkscape.app/Contents/MacOS/inkscape --version

Setup

uv sync

Run tests:

uv run pytest

Run the MCP smoke test:

/Users/chrisgutierrez/.local/bin/uv run embroidery-mcp-smoke

Run the MCP server:

/Users/chrisgutierrez/.local/bin/uv run embroidery-mcp

The server uses stdio transport and is intended to be launched by an MCP client.

Register with Codex:

./scripts/install-codex-mcp.sh

List configured Codex MCP servers:

codex mcp list

MCP Tool

validate_svg

Input:

{
  "path": "examples/simple-text.svg"
}

Output:

{
  "valid": true,
  "errors": [],
  "warnings": [],
  "stats": {
    "elements": 3,
    "paths": 1,
    "shapes": 2,
    "colors": 3
  }
}

The tool checks:

• file existence
• XML parseability
• SVG root element
• element, path, shape, and color counts
• obvious open path warnings
• tiny object warnings
• unsupported SVG feature warnings

cleanup_svg

Input:

{
  "path": "examples/cleanup-source.svg",
  "output_path": "examples/cleanup-source-cleaned.svg"
}

Output:

{
  "cleaned": true,
  "input_path": "examples/cleanup-source.svg",
  "output_path": "examples/cleanup-source-cleaned.svg",
  "removed_elements": ["metadata", "title", "desc", "script", "foreignObject", "g"],
  "warnings": [],
  "errors": []
}

The tool removes:

• script
• foreignObject
• metadata
• title
• desc
• empty groups with no attributes

simulate_design

Input:

{
  "path": "examples/simple-text.svg"
}

Output:

{
  "ready": false,
  "estimated_stitches": 2050,
  "color_sequence": ["#1f77b4", "#111111", "#d62728"],
  "warnings": ["Path appears open; open paths may create running stitches or jump risks."],
  "recommendations": ["Review open paths; close filled regions or mark intentional running stitches."]
}

This is a pure-Python readiness simulation. It does not run Ink/Stitch yet.

analyze_design

Input:

{
  "path": "examples/simple-text.svg"
}

Output includes object classification, color sequence, candidate counts, warnings, and operator recommendations. Stitch candidates are recommendations only; v1 does not write Ink/Stitch stitch parameters automatically.

check_environment

Input:

{}

Output:

{
  "ready_for_inkstitch": true,
  "inkscape": {
    "available": true,
    "path": "/Applications/Inkscape.app/Contents/MacOS/inkscape",
    "version": "Inkscape 1.4.4 (dcaf3e7, 2026-05-05)"
  },
  "inkstitch": {
    "available": true,
    "app_path": "/Users/chrisgutierrez/Library/Application Support/org.inkscape.Inkscape/config/inkscape/extensions/inkstitch/inkstitch.app",
    "binary_path": "/Users/chrisgutierrez/Library/Application Support/org.inkscape.Inkscape/config/inkscape/extensions/inkstitch/inkstitch.app/Contents/MacOS/inkstitch",
    "match_count": 289
  },
  "recommendations": ["Environment is ready for Ink/Stitch-backed tools."]
}

This tool checks the local Mac app path for Inkscape and common user/app extension paths for Ink/Stitch.

generate_preview

Input:

{
  "path": "examples/simple-text.svg",
  "output_path": "examples/simple-text.png"
}

Output:

{
  "generated": true,
  "output_path": "examples/simple-text.png",
  "format": "png",
  "bytes": 1252,
  "errors": []
}

generate_stitch_plan

Input:

{
  "path": "examples/simple-text.svg",
  "output_path": "examples/simple-text.stitch-plan.svg"
}

Output:

{
  "generated": true,
  "output_path": "examples/simple-text.stitch-plan.svg",
  "format": "svg",
  "errors": []
}

export_embroidery

Input:

{
  "path": "examples/simple-text.svg",
  "output_path": "examples/simple-text.dst",
  "file_format": "dst"
}

Output:

{
  "exported": true,
  "output_path": "examples/simple-text.dst",
  "format": "dst",
  "bytes": 1914,
  "errors": []
}

V1 verifies dst and pes.

create_operator_package

Input:

{
  "path": "examples/simple-text.svg",
  "output_dir": "examples/simple-text-embroidery",
  "formats": ["dst", "pes"]
}

Output artifacts:

• cleaned SVG
• PNG preview
• SVG stitch plan
• DST file
• PES file
• report.json
• report.md

This is the main v1 workflow for operators.

vectorize_image

Input:

{
  "path": "examples/simple-logo.png",
  "output_path": "examples/simple-logo.vectorized.svg",
  "max_colors": 6,
  "max_dimension": 160,
  "remove_background": true
}

Output:

{
  "vectorized": true,
  "output_path": "examples/simple-logo.vectorized.svg",
  "colors": ["#1f77b4", "#d62728"],
  "rectangles": 42,
  "errors": []
}

This creates a layered SVG with one Inkscape layer per reduced color. It is intended for logos and flat artwork first; complex photos may need manual cleanup.

create_image_operator_package

Input:

{
  "path": "examples/simple-logo.png",
  "output_dir": "examples/simple-logo-embroidery",
  "formats": ["dst", "pes"],
  "max_colors": 6,
  "max_dimension": 160
}

This is the image-entry workflow. It writes a vectorized SVG, then produces the same cleaned SVG, previews, DST/PES files, and operator reports as create_operator_package.

Example MCP Config

Use the absolute repo path for reliability:

{
  "mcpServers": {
    "embroidery-mcp": {
      "command": "/Users/chrisgutierrez/.local/bin/uv",
      "args": [
        "--directory",
        "/Users/chrisgutierrez/Projects/InkStitchMCP",
        "run",
        "embroidery-mcp"
      ]
    }
  }
}

Roadmap

Phase 1:

• validate_svg
• cleanup_svg
• simulate_design
• analyze_design
• check_environment
• generate_preview
• generate_stitch_plan
• export_embroidery
• create_operator_package

Future improvements:

• better bitmap tracing for photos
• smarter object merging and simplification
• automatic stitch parameter assignment
• thread palette matching

Phase 2:

• analyze_design(svg)
• warnings for tiny objects, excessive density, open paths, overlaps, and jump stitch risks

Phase 3:

• assign_stitches(svg)
• fill, satin, and running stitch recommendations

Phase 4:

• generate_preview(svg)
• PNG preview, stitch simulation, and color sequence

Phase 5:

• export_embroidery(svg)
• PES, DST, EXP, JEF, and VP3 export

Disclaimer

Embroidery digitizing is both technical and artistic. AI-generated designs should be reviewed and test-stitched before production use.