Sketchwright
Sketchwright is an MCP server for deterministic Excalidraw diagram generation, validation, layout, update, and export.
Create Excalidraw-compatible diagram scenes from a structured specification or text DSL, with optional layout overrides and output files.
Validate diagram specifications or Excalidraw scenes for schema conformance and bindings.
Compute deterministic node positions, bounding boxes, and edge routes using selectable layout algorithms and directions.
Export diagrams to
.excalidrawJSON or standalone.svg.Incrementally update existing diagram specifications by adding/removing/renaming nodes and adding/removing edges, then regenerate scenes.
Discover supported shapes, layout algorithms, directions, and resource limits.
Generates deterministic, fully editable Excalidraw-compatible scenes (.excalidraw) using the Excalidraw v2 schema, including native shape bindings and centered bound text, so diagrams can be opened and edited in Excalidraw.
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., "@Sketchwright Create a three-tier web app diagram and export it as an editable Excalidraw scene"
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.
Sketchwright
Deterministic Excalidraw diagram agent, layout engine, and Model Context Protocol (MCP) server.
Status: Beta (v0.1.0). Fully functional MCP server, standalone Python engine, and CLI; production-ready for automated diagram generation.
Quick Facts
Dimension | Specification | Evidence / Details |
Package Name |
| Defined in |
Runtime Requirement | Python | Tested on Python 3.12 ( |
Protocol Support | Model Context Protocol (MCP) 2.3.0 | 6 tools, 3 resources, 3 prompts over |
Output Formats |
| Verified reciprocal arrow bindings & multiline text containers |
Layout Algorithms | Layered (Sugiyama), Grid, Tree | Deterministic cycle breaking, 4 directions ( |
External Dependencies | Zero external LLM or cloud services required | Pure local layout and scene serialization |
Primary Entry Points |
| Module execution via |
License | MIT License | Verified in |
Related MCP server: Excalidraw Architect MCP
Overview
Sketchwright is a developer-oriented Model Context Protocol (MCP) diagram agent and standalone Python engine. It translates structured diagram specifications and lightweight textual DSL into deterministic, visually balanced, and fully editable Excalidraw-compatible scenes (.excalidraw) as well as standalone SVG.
A language model in an MCP-compatible host (such as Claude Desktop, VS Code, or Antigravity) decides what the diagram should represent; Sketchwright's deterministic engine decides how that specification is validated, positioned, routed, and serialized.
Core Product Principle
Structured intent in; validated, editable diagram scene out.
Core layout, validation, and generation capabilities require no paid model APIs, cloud accounts, API keys, or external LLM service.
Quick Start
Generate a complete, editable Excalidraw diagram scene in fewer than five steps:
In POSIX Shells (Linux / macOS)
# 1. Clone the repository
git clone https://github.com/manoj-025/sketchwright-mcp.git
cd sketchwright-mcp
# 2. Install dependencies with uv
uv sync --all-groups
# 3. Generate an Excalidraw diagram from the sample architecture
uv run sketchwright generate examples/architecture.json -o architecture.excalidraw --overwriteIn PowerShell (Windows)
# 1. Clone the repository
git clone https://github.com/manoj-025/sketchwright-mcp.git
Set-Location sketchwright-mcp
# 2. Install dependencies with uv
uv sync --all-groups
# 3. Generate an Excalidraw diagram from the sample architecture
uv run sketchwright generate examples/architecture.json -o architecture.excalidraw --overwriteExpected result:
Generated diagram written to: architecture.excalidrawYou can drag and drop architecture.excalidraw directly into Excalidraw.com or open it inside the Excalidraw VS Code extension.
Features
Model Context Protocol (MCP 2.x) Integration: Exposes 6 dedicated tools (
sketchwright_create_diagram,sketchwright_update_diagram,sketchwright_validate_diagram,sketchwright_layout_diagram,sketchwright_export_diagram,sketchwright_get_capabilities), 3 resources, and 3 prompt templates over standard input/output (stdio).Strict Stdio Discipline: Guarantees that MCP JSON-RPC protocol framing is never polluted by application logs; all diagnostics are routed strictly to
sys.stderr.Deterministic Layered Layout (Sugiyama Engine):
Cycle detection and feedback edge set condensation to guarantee termination on cyclic graphs.
Longest-path rank assignment and barycentric crossing reduction.
Multi-directional flow: Left-to-Right (
LR), Right-to-Left (RL), Top-to-Bottom (TB), and Bottom-to-Top (BT).Graceful handling of disconnected clusters, self-loops, and parallel edges.
True Excalidraw v2 Schema & Reciprocal Bindings:
Validates and generates native
startBinding,endBinding, containerboundElements, and centered bound text containers.Fully editable in Excalidraw.com or the Excalidraw VS Code / Obsidian extensions.
Visual Grouping & Boundaries: Declared groups serialize with member container tracking and dashed boundary rectangles.
Incremental Diagram Mutation: Iteratively patch diagrams (add/remove nodes, prune connected edges, update labels) via stable ID matching with ambiguous-match fallback protection.
Standalone CLI & Public Python API: Complete functionality accessible as a CLI utility or embedded library without requiring an active MCP host.
Defensive Resource Limits: Enforces input payload limits (1 MB), node counts (500), edge counts (1000), label lengths (256 chars), and path traversal boundary checks.
Clean SVG Export: Standalone valid SVG renderer with
<tspan>multiline text wrapping, arrow markers, and XML escaping.
Supported Diagram Types
Software & Cloud Architecture: Multi-tier web applications, client/server models, API gateways, database clusters.
Microservices & Data-Flow Topologies: Service meshes, message brokers, caching tiers, storage clusters.
Decision Trees & Process Flowcharts: Branching logic, validation flows, decision nodes.
State-Transition Diagrams & Cyclic Networks: Finite state machines, feedback loops, retry circuits.
CI/CD Pipelines & Roadmaps: Build, test, security audit, and deployment stages.
Supported Shapes
Shape Identifier | Visual Representation | Common Use Case |
| Standard sharp box | Services, modules, UI components, microservices |
| Rounded container | Queues, consumers, workers, terminal steps |
| Elliptical container | Start/stop states, events, terminal nodes |
| Rhombus / Diamond | Decision conditions, branching logic |
| Storage drum | Databases, caches, file storage, data lakes |
| Frameless text block | Standalone annotations, notes, titles |
Prerequisites & Installation
Prerequisites
Python: 3.12 or newer.
Package Manager: uv (recommended) or standard
pip.Supported Operating Systems: Windows, Linux, macOS.
Installation via uv (Recommended)
# Clone the repository
git clone https://github.com/manoj-025/sketchwright-mcp.git
cd sketchwright-mcp
# Install dependencies into isolated virtual environment
uv sync --all-groupsInstallation via pip
# Clone and install in editable mode with development dependencies
git clone https://github.com/manoj-025/sketchwright-mcp.git
cd sketchwright-mcp
python -m venv .venv
# Activate environment (POSIX: source .venv/bin/activate | Windows: .venv\Scripts\Activate.ps1)
pip install -e ".[dev]"Public Python API
Sketchwright exports a fully typed public Python API:
from sketchwright import (
generate_diagram,
validate_diagram,
layout_diagram,
export_diagram,
update_diagram,
get_capabilities,
)
spec = {
"schema_version": "1.0",
"title": "Cloud Microservice Architecture",
"layout": {"algorithm": "layered", "direction": "LR"},
"nodes": [
{"id": "gateway", "label": "API Gateway", "shape": "rectangle"},
{"id": "auth", "label": "Auth Service", "shape": "rounded_rectangle"},
{"id": "db", "label": "User Store", "shape": "cylinder"},
],
"edges": [
{"id": "e1", "source": "gateway", "target": "auth", "label": "JWT Verify"},
{"id": "e2", "source": "auth", "target": "db", "label": "SQL Query"},
],
}
# 1. Generate full Excalidraw scene
result = generate_diagram(spec, output_path="architecture.excalidraw", overwrite=True)
print(f"Valid Scene: {result.validation.is_valid}")
print(f"Canvas Size: {result.laid_out.canvas_rect.width} x {result.laid_out.canvas_rect.height}")
print(f"Total Elements: {len(result.scene['elements'])}")Expected output:
Valid Scene: True
Canvas Size: 853.0 x 310.0
Total Elements: 7See examples/hello_world.py for a complete standalone runnable script.
Command-Line Interface
Sketchwright provides the sketchwright executable (and module invocation via python -m sketchwright).
Exit Code Policy
Exit Code | Classification | Description |
| Success | Command completed successfully. |
| User / Validation Error | Schema validation failure, syntax error, or invalid CLI flag. |
| Internal / Filesystem Error | Unexpected runtime exception or filesystem access error. |
Common Commands
# Inspect version and CLI help
uv run sketchwright --version
uv run sketchwright --help
# Query runtime capabilities and limits
uv run sketchwright capabilities
# Validate a diagram specification or Excalidraw scene
uv run sketchwright validate examples/architecture.json
uv run sketchwright validate my_diagram.excalidraw
# Generate an Excalidraw scene file (.excalidraw)
uv run sketchwright generate examples/architecture.json -o web_arch.excalidraw --overwrite
# Generate an SVG file (.svg)
uv run sketchwright generate examples/flowchart.json -o flowchart.svg --format svg --overwrite
# Compute raw geometry and routing coordinates without writing a scene
uv run sketchwright layout examples/architecture.json --direction LR
# Launch the MCP server over standard input/output
uv run sketchwright mcpSample output from uv run sketchwright validate examples/architecture.json:
Validation result for architecture.json: VALIDMCP Server Integration
To register Sketchwright in an MCP client (such as Claude Desktop, VS Code, or Google Antigravity), add the following entry to your host's MCP configuration file (e.g., mcpServers object):
{
"mcpServers": {
"sketchwright": {
"command": "uv",
"args": [
"run",
"--directory",
"<PATH_TO_SKETCHWRIGHT_MCP>",
"sketchwright",
"mcp"
]
}
}
}Note: Replace
<PATH_TO_SKETCHWRIGHT_MCP>with the absolute path to your clonedsketchwright-mcpdirectory (use forward slashes/on all platforms).
Registered MCP Tools
Tool Name | Purpose | Key Parameters |
| Generates complete Excalidraw scene JSON from specification or text DSL. |
|
| Incrementally mutates an existing specification (add/remove nodes, edges) and regenerates scene. |
|
| Validates a diagram specification or Excalidraw scene for schema conformance and bindings. |
|
| Computes deterministic node coordinates, canvas bounds, and edge routes without serialization. |
|
| Exports a diagram specification or scene to |
|
| Returns machine-readable report of supported shapes, algorithms, directions, and limits. | None |
Registered MCP Resources & Prompts
Resources:
schema://v1.0: Canonical JSON Schema forDiagramSpec.capabilities://manifest: Runtime capability and limits manifest.guide://usage: Comprehensive prompt engineering guide and diagram patterns.
Prompts:
architecture_diagram: Prompt guide for structured software architecture requests.flowchart_diagram: Prompt guide for workflow/decision flowcharts.dependency_graph: Prompt guide for software/package dependency graphs.
Agent Skill Integration (SKILL.md)
Sketchwright includes a universal open-standard agent skill definition located in skill/SKILL.md, fully compatible with Claude Code, Cursor, GitHub Copilot, Codex, and agent skill marketplaces like Agensi.io.
Skill Manifest:
skill/SKILL.mdMCP Client Configuration:
skill/references/mcp-config.jsonQuickstart Guide:
skill/references/quickstart.md
Configuration
Sketchwright works out of the box with zero external configuration. Settings can be customized via environment variables (or a local .env file; see .env.example).
Precedence Order
Explicit API / CLI Argument / Tool Parameter (highest precedence)
Diagram Specification
layoutblockEnvironment Variables (
SKETCHWRIGHT_*)Internal Default Settings (lowest precedence)
Environment Variables
Variable | Type | Default | Description | Secret |
| string |
| Logging level ( | No |
| string |
| Default layout algorithm ( | No |
| string |
| Default layout direction ( | No |
| float |
| Intra-rank spacing between adjacent nodes in pixels. | No |
| float |
| Distance between consecutive ranks/layers in pixels. | No |
| float |
| Outer canvas margin around diagram bounds in pixels. | No |
| int |
| Maximum allowed input payload size in bytes (1 MB). | No |
| int |
| Maximum number of nodes permitted per diagram. | No |
| int |
| Maximum number of edges permitted per diagram. | No |
| int |
| Maximum permitted characters for any label. | No |
| string | unset | Path boundary: restricts file outputs to an authorized root. | No |
Canonical Specification Format
{
"schema_version": "1.0",
"title": "Example Web Architecture",
"layout": {
"algorithm": "layered",
"direction": "LR",
"node_spacing": 80.0,
"rank_spacing": 120.0,
"padding": 40.0
},
"style": {
"theme": "light",
"font_size": 18,
"stroke_width": 2
},
"nodes": [
{ "id": "browser", "label": "Web Browser", "shape": "rectangle" },
{ "id": "api", "label": "API Server", "shape": "rounded_rectangle" },
{ "id": "database", "label": "Database", "shape": "cylinder" }
],
"edges": [
{ "id": "e1", "source": "browser", "target": "api", "label": "HTTPS", "kind": "directed" },
{ "id": "e2", "source": "api", "target": "database", "label": "SQL", "kind": "directed" }
],
"groups": [
{ "id": "backend", "label": "Backend Tier", "node_ids": ["api", "database"] }
],
"options": {
"deterministic": true
}
}See docs/architecture/Schema.md for detailed schema specifications.
Project Structure
Derived from verified repository source files:
sketchwright-mcp/
├── .github/workflows/ci.yml # Cross-platform GitHub Actions CI (Linux, Windows)
├── docs/ # Comprehensive technical documentation suite
│ ├── README.md # Documentation suite index & master navigation map
│ ├── product/ # PRD, user journeys, app flows, and terminology glossary
│ │ ├── PRD.md # Product Requirements Document
│ │ ├── AppFlow.md # State inventory, CLI trees & MCP protocol lifecycles
│ │ └── Glossary.md # Canonical terminology & domain dictionary
│ ├── architecture/ # Technical specs, design tokens, schemas, APIs & ADRs
│ │ ├── TechSpec.md # System design, layout pipeline & C4 architecture
│ │ ├── Design.md # Visual identity & Excalidraw styling tokens
│ │ ├── Schema.md # Canonical specification & Pydantic data models
│ │ ├── API.md # FastMCP tool signatures & CLI contracts
│ │ └── decisions/ # Architecture Decision Records (ADRs)
│ ├── guides/ # Operational runbooks, configurations & user handbooks
│ │ ├── configuration.md # Environment variables & tuning limits
│ │ ├── Deployment.md # Build, release, PyPI publishing & client configs
│ │ ├── troubleshooting.md # Diagnostic procedures & error resolutions
│ │ └── SecurityAndCompliance.md # STRIDE threat model & security boundaries
│ └── development/ # Engineering standards, testing & code quality
│ ├── Rules.md # Engineering guidelines & code quality standards
│ └── testing.md # Test strategy, critical test cases & coverage
├── examples/ # Runnable samples and test fixtures
│ ├── architecture.json # Multi-tier microservice architecture spec
│ ├── flowchart.json # Branching process flowchart spec
│ ├── hello_world.py # Public Python API usage example
│ └── mcp-client-config.example.json # Generic MCP client host config
├── src/sketchwright/ # Core application package
│ ├── engine/ # Diagram generator and update engine
│ ├── excalidraw/ # Excalidraw serializer, validator, and SVG export
│ ├── layout/ # Sugiyama layout, geometry, and stepped routing
│ ├── mcp/ # MCP 2.x server, tools, resources, and prompts
│ ├── models/ # Pydantic v2 schemas and validation models
│ ├── parser/ # Structured JSON and text DSL parsers
│ ├── cli.py # Command-line interface subcommands
│ ├── config.py # Settings and defensive limit management
│ └── logging_config.py # Strict stdio/stderr routing
├── tests/ # Multi-level automated test suite (91 tests)
│ ├── contract/ # MCP protocol and tool discovery tests
│ ├── e2e/ # Subprocess stdio integration tests
│ ├── integration/ # Pipeline execution and determinism tests
│ └── unit/ # Unit tests for CLI, models, layout, and export
├── .env.example # Environment variable template
├── CHANGELOG.md # Version release notes (Keep a Changelog)
├── CONTRIBUTING.md # Contribution guidelines and setup steps
├── LICENSE # MIT License
├── pyproject.toml # Package manifest and tool configuration
└── SECURITY.md # Vulnerability reporting and security architectureTesting & Verification
Sketchwright includes an automated test suite across unit, integration, contract, and end-to-end levels:
# Run the complete test suite (91 tests)
uv run pytest -v
# Run code style and formatting checks
uv run ruff check .
uv run ruff format --check .
# Run static type checking with Mypy in strict mode
uv run mypy src
# Validate package build
uv buildObserved test status: 91 passed in 4.19s (100% pass rate).
Known Limitations
Approximate Font Metrics: To avoid heavy binary font rendering dependencies (such as HarfBuzz or FreeType), Sketchwright computes bounding boxes using deterministic character width heuristics. Browser rendering in Excalidraw may show minor visual variations depending on locally installed fallback fonts.
Simplified Edge Routing: Orthogonal stepped routing avoids node interiors and handles backward loops; complex multi-hop obstacle avoidance routes around rank boundaries rather than sub-pixel collision routing.
Manual Host Configuration: MCP client hosts (Claude Desktop, VS Code, Antigravity) require manual registration by appending the server configuration block to their respective configuration files.
Security Architecture
Strict Resource Bounds: Limits input payloads to 1 MB (
SKETCHWRIGHT_MAX_INPUT_BYTES), 500 nodes (SKETCHWRIGHT_MAX_NODES), 1000 edges (SKETCHWRIGHT_MAX_EDGES), and 256 characters per label (SKETCHWRIGHT_MAX_LABEL_LENGTH).Filesystem Boundary Isolation: File writes are executed atomically using temporary files followed by atomic replacement. Traversal sequences (
../) are detected and rejected. Output directory restrictions can be enforced viaSKETCHWRIGHT_ALLOWED_DIR.Zero Dynamic Code Execution: The codebase contains zero calls to
eval,exec, or dynamic module loading.Protocol Isolation: Standard output (
stdout) is strictly reserved for MCP JSON-RPC protocol messages; all application logs and diagnostics are directed exclusively tostderr.
For vulnerability disclosure procedures, see SECURITY.md.
Contributing
Contributions are welcome. Please read CONTRIBUTING.md for workflow instructions, code standards, and local quality check commands.
All pull requests must pass formatting (ruff format), linting (ruff check), static type analysis (mypy src), and the full test suite (pytest -v).
License
Distributed under the MIT License. See LICENSE for the full text.
Copyright (c) 2026 Sketchwright Contributors.
Available Tools
6 toolssketchwright_create_diagramC
Generate an Excalidraw-compatible diagram scene JSON from a structured specification or DSL.
Inputs: text_dsl, overwrite, output_path, specification, +1 more. Returns: object
sketchwright_export_diagramC
Export a diagram specification or Excalidraw scene to .excalidraw JSON or standalone .svg.
Inputs: scene, format, overwrite, output_path, +1 more. Returns: object
sketchwright_get_capabilitiesA
Discover Sketchwright's supported shapes, layout algorithms, directions, and resource limits.
Inputs: no named parameters. Returns: object
sketchwright_layout_diagramC
Calculate deterministic node positions, bounding boxes, and edge routes for a diagram.
Inputs: specification (required), algorithm, direction. Returns: object
sketchwright_update_diagramC
Incrementally update an existing diagram specification (add/remove/rename nodes, add/remove edges) and regenerate scene.
Inputs: patch (required), specification (required), overwrite, output_path, +1 more. Returns: object
sketchwright_validate_diagramB
Validate a diagram specification or an Excalidraw scene JSON for schema conformance and bindings.
Inputs: scene, specification. Returns: object
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 6 tools
Each tool maps to a distinct stage in the diagram lifecycle: create, layout, update, validate, export, and capability discovery. The boundaries between create and layout are clarified by their descriptions, so an agent can reliably choose the right operation.
All tool names use the same sketchwright_ prefix followed by a consistent verb_noun pattern in snake_case. There are no mixed conventions or vague standalone verbs.
Six tools is well-scoped for a diagram generation server, covering creation, layout, updating, validation, export, and discovery without redundancy. Each tool has a clear, non-overlapping role.
The surface covers the core diagram lifecycle from specification creation through validation and export, including incremental updates and capability discovery. Minor gaps exist around persisted diagram management (e.g., listing or deleting saved diagrams), but these are not essential for the stated purpose.
Maintenance
Related MCP Connectors
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Polished system design diagrams (SVG/PNG) from a tiny YAML spec, ~18x fewer tokens than raw SVG.
Make editable flowcharts, process charts, funnels, timelines and data models from plain language.
AI agent draws editable hand-drawn diagrams (flowchart, ER, architecture) via MCP, not static images
Related MCP Servers
- AlicenseAqualityDmaintenanceGenerates Excalidraw architecture diagrams with support for 60+ components including GCP, Kafka, and AI/Agentic shapes. Provides MCP tools for creating, modifying, and converting diagrams from structured input or Mermaid syntax.41MIT
- FlicenseNot gradedqualityAmaintenanceEnables AI assistants to turn plain-language descriptions of systems, flows, and data into 25 kinds of fully laid-out, hand-drawn Excalidraw diagrams — architecture, sequence, ER, swimlane, Gantt, charts and more — with auto-styling for 50+ technologies and revision in natural language. Runs fully offline, exports to SVG and PNG without a browser or Node.js, and can optionally persist the architecture as a queryable knowledge graph.-
- FlicenseNot gradedqualityAmaintenanceEnables AI coding tools to turn architecture and other structured descriptions into auto-laid-out, hand-drawn Excalidraw diagrams across 25 diagram types, including architecture, flowcharts, sequence, ER, swimlanes, timelines, Gantt, and charts. It also supports natural-language revision, SVG/PNG export, and optionally a queryable knowledge graph of the system.-
- AlicenseNot gradedqualityBmaintenanceGives AI agents a live, persistent diagram canvas they can draw on, inspect via screenshots, and refine element by element, then export as editable .excalidraw files to commit alongside code. Supports architecture diagrams and flowcharts through a CLI, MCP tools, or REST API.MIT