Getting Started

Installation

drawmode runs as an MCP server. No separate install is needed — npx handles it.

# Claude Code / Cursor (stdio mode)
npx drawmode --stdio

# HTTP mode (Streamable HTTP on port 3001)
npx drawmode

Client Configuration

MCP Client Configuration

Add this to your MCP client’s configuration file:

• Claude Code: ~/.claude/settings.json or project .mcp.json
• Claude Desktop (macOS): ~/Library/Application Support/Claude/claude_desktop_config.json
• Claude Desktop (Windows): %APPDATA%\Claude\claude_desktop_config.json
• Cursor: Cursor MCP settings

{
  "mcpServers": {
    "drawmode": {
      "command": "npx",
      "args": ["drawmode", "--stdio"]
    }
  }
}

Your First Diagram

Once configured, ask your LLM to draw a diagram. The LLM receives three tools — draw (generate/edit), draw_describe (convert existing .excalidraw to code), and draw_info (capabilities reference) — and writes TypeScript code against the Diagram SDK:

const d = new Diagram();
const web = d.addBox("Web App", { row: 0, col: 0, color: "frontend" });
const api = d.addBox("API Server", { row: 0, col: 1, color: "backend" });
const db = d.addBox("Database", { row: 1, col: 1, color: "database" });
d.connect(web, api, "REST");
d.connect(api, db, "queries");
return d.render({ format: "url" });

This produces a shareable excalidraw.com URL printed in the tool response. Click it to view and edit the diagram in your browser. For local files, use format: "excalidraw" — this writes a .excalidraw file you can open directly in VS Code (with the Excalidraw extension) or drag into excalidraw.com.

Output Formats

Format	Description	Works in
excalidraw	.excalidraw JSON file	Claude Code, Cursor, VS Code
url	Shareable excalidraw.com link	All clients
png	PNG image (requires puppeteer)	Local with puppeteer, Cloudflare Worker
svg	SVG markup	Local with puppeteer

How It Works

1. LLM receives one tool (draw) with TypeScript type definitions
2. LLM writes code against the Diagram SDK
3. Executor runs the code — SDK validates every call (invalid IDs throw clear errors the LLM can self-correct on)
4. Zig WASM (with Graphviz statically linked) handles layout and edge routing
5. WASM validation checks the rendered output for structural correctness
6. Output: .excalidraw file, excalidraw.com URL, PNG, or SVG

Starting from Mermaid

Already have a Mermaid diagram? Use fromMermaid() as a starting point, then refine with the full SDK:

const d = Diagram.fromMermaid(`
  graph TD
    A[API Gateway] --> B[Auth Service]
    A --> C[Order Service]
    B --> D[(Database)]
`);
d.updateNode(d.findByLabel("API Gateway")[0], { color: "backend" });
return d.render();

See Iterating on Diagrams for supported Mermaid syntax.

Troubleshooting

Diagram is blank or missing elements? Check that your code returns d.render() — a missing return statement is the most common cause.

PNG/SVG export fails? Install puppeteer: npm install puppeteer. It’s optional — other formats work without it.

“Cannot find module” errors? Make sure npx drawmode --stdio runs successfully on its own before configuring your MCP client.