Excalidraw Diagrams

Create diagrams using the Excalidraw canvas server and verify output with screenshots.

Prerequisites

1. Canvas server running at http://localhost:3000

   cd ${MCP_EXCALIDRAW_PATH:-~/code/mcp_excalidraw} && npm run canvas
   

   Set MCP_EXCALIDRAW_PATH in your global mise config (~/.config/mise/config.toml) if the path differs.

2. MCP server configured in project .mcp.json (for MCP tool access)

Creating Diagrams

Via HTTP API (Recommended)

Create elements directly via the canvas server API:

curl -X POST http://localhost:3000/api/elements/batch \
  -H "Content-Type: application/json" \
  -d @/tmp/elements.json

Element JSON structure:

{
  "elements": [
    {"type": "rectangle", "x": 100, "y": 100, "width": 150, "height": 80, "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2"},
    {"type": "text", "x": 120, "y": 130, "text": "Label", "fontSize": 20}
  ]
}

Element Types

| Type | Required Props | Optional Props | |------|---------------|----------------| | rectangle | x, y, width, height | backgroundColor, strokeColor, strokeWidth | | ellipse | x, y, width, height | backgroundColor, strokeColor | | diamond | x, y, width, height | backgroundColor, strokeColor | | text | x, y, text | fontSize, fontFamily | | arrow | x, y, width, height | strokeColor, strokeWidth | | line | x, y, width, height | strokeColor, strokeWidth |

Color Palette

• Blue: #a5d8ff (bg), #1971c2 (stroke)
• Green: #b2f2bb (bg), #2f9e44 (stroke)
• Red: #ffc9c9 (bg), #e03131 (stroke)
• Yellow: #ffec99 (bg), #f08c00 (stroke)
• Purple: #d0bfff (bg), #7950f2 (stroke)
• Gray: #dee2e6 (bg), #495057 (stroke)

Verifying Output

Take a screenshot to verify the diagram rendered correctly:

from playwright.sync_api import sync_playwright

with sync_playwright() as p:
    browser = p.chromium.launch(headless=True)
    page = browser.new_page()
    page.goto('http://localhost:3000')
    page.wait_for_load_state('networkidle')
    page.wait_for_timeout(2000)
    page.screenshot(path='/tmp/diagram.png', full_page=True)
    browser.close()

Run with: uv run python /tmp/screenshot_script.py

Then read the screenshot to verify: Read /tmp/diagram.png

Common Patterns

Flowchart (Vertical)

{
  "elements": [
    {"type": "rectangle", "x": 100, "y": 50, "width": 120, "height": 60, "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2"},
    {"type": "text", "x": 130, "y": 70, "text": "Start", "fontSize": 16},
    {"type": "arrow", "x": 160, "y": 110, "width": 0, "height": 40, "strokeColor": "#495057"},
    {"type": "rectangle", "x": 100, "y": 150, "width": 120, "height": 60, "backgroundColor": "#b2f2bb", "strokeColor": "#2f9e44"},
    {"type": "text", "x": 120, "y": 170, "text": "Process", "fontSize": 16},
    {"type": "arrow", "x": 160, "y": 210, "width": 0, "height": 40, "strokeColor": "#495057"},
    {"type": "rectangle", "x": 100, "y": 250, "width": 120, "height": 60, "backgroundColor": "#ffc9c9", "strokeColor": "#e03131"},
    {"type": "text", "x": 135, "y": 270, "text": "End", "fontSize": 16}
  ]
}

Architecture Boxes (Horizontal)

{
  "elements": [
    {"type": "rectangle", "x": 50, "y": 100, "width": 100, "height": 80, "backgroundColor": "#a5d8ff", "strokeColor": "#1971c2"},
    {"type": "text", "x": 70, "y": 130, "text": "Client", "fontSize": 14},
    {"type": "arrow", "x": 150, "y": 140, "width": 50, "height": 0, "strokeColor": "#495057"},
    {"type": "rectangle", "x": 200, "y": 100, "width": 100, "height": 80, "backgroundColor": "#b2f2bb", "strokeColor": "#2f9e44"},
    {"type": "text", "x": 225, "y": 130, "text": "API", "fontSize": 14},
    {"type": "arrow", "x": 300, "y": 140, "width": 50, "height": 0, "strokeColor": "#495057"},
    {"type": "rectangle", "x": 350, "y": 100, "width": 100, "height": 80, "backgroundColor": "#d0bfff", "strokeColor": "#7950f2"},
    {"type": "text", "x": 385, "y": 130, "text": "DB", "fontSize": 14}
  ]
}

API Endpoints

| Endpoint | Method | Description | |----------|--------|-------------| | /api/elements | GET | List all elements | | /api/elements | POST | Create single element | | /api/elements/batch | POST | Create multiple elements | | /api/elements/:id | PUT | Update element | | /api/elements/:id | DELETE | Delete element | | /api/elements/from-mermaid | POST | Convert Mermaid to elements | | /health | GET | Server health check |

Workflow

1. Check canvas server is running: curl http://localhost:3000/health
2. Clear canvas if needed: Click "Clear Canvas" in browser or restart server
3. Create elements via API batch endpoint
4. Take screenshot to verify
5. Show screenshot to user for confirmation
6. Iterate if needed

Mermaid Conversion

Convert Mermaid diagrams to Excalidraw:

curl -X POST http://localhost:3000/api/elements/from-mermaid \
  -H "Content-Type: application/json" \
  -d '{"mermaidDiagram": "graph TD; A-->B; B-->C;"}'

Note: Mermaid conversion requires the browser canvas to be open for rendering.