Excalidraw Diagram Agent

Built as a portfolio project proving MCP breadth beyond data-query tools: this server takes a described system and produces a real, editable diagram file — not a data lookup, a generative/creative tool exposed the same way as the data-query MCP server in this portfolio.

excalidraw-diagram-agent

An MCP server that turns a described system into a real, editable .excalidraw diagram file. Describe an architecture in Claude Desktop ("draw me a diagram of a client talking to an API gateway, which routes to an auth service and an order service, both writing to Postgres") and get back a file you can open and keep editing in Excalidraw.

What's here

• layout.py — a simple layered graph layout (no external graph library): positions nodes left-to-right by distance from a root, stacked vertically within each layer.
• excalidraw_gen.py — builds valid .excalidraw JSON: rectangles with properly bound text labels (they move together in the editor) and arrows with real startBinding/endBinding (they stay attached when you drag a box) — not just static lines dropped at fixed coordinates.
• server.py — the MCP server, one tool: generate_diagram(title, nodes, edges).
• requirements.txt — one dependency, pinned.

1. Setup

cd excalidraw-diagram-agent
python3 -m venv venv
source venv/bin/activate
pip install -r requirements.txt

2. Test it standalone (no Claude needed yet)

python3 -c "
from server import generate_diagram
print(generate_diagram(
    title='Order Processing System',
    nodes=[
        {'id': 'client', 'label': 'Web Client'},
        {'id': 'gateway', 'label': 'API Gateway'},
        {'id': 'auth', 'label': 'Auth Service'},
        {'id': 'orders', 'label': 'Order Service'},
        {'id': 'db', 'label': 'Postgres DB'},
    ],
    edges=[
        {'from': 'client', 'to': 'gateway'},
        {'from': 'gateway', 'to': 'auth'},
        {'from': 'gateway', 'to': 'orders'},
        {'from': 'auth', 'to': 'db'},
        {'from': 'orders', 'to': 'db'},
    ],
))
"

Should print a confirmation with the file path. Open the generated file at excalidraw.com (File > Open, or just drag the .excalidraw file onto the page) to see the actual diagram.

3. Connect it to Claude Desktop

Same pattern as the rental-data MCP server (project 1) — add a second entry to the same config file, ~/Library/Application Support/Claude/claude_desktop_config.json, alongside your existing mcpServers block:

"diagram-agent": {
  "command": "/absolute/path/to/excalidraw-diagram-agent/venv/bin/python3",
  "args": ["/absolute/path/to/excalidraw-diagram-agent/server.py"]
}

(Both servers can live in the same mcpServers object — don't replace rental-data, add diagram-agent next to it.) Fully quit and reopen Claude Desktop, then check Settings > Developer to confirm both show as running.

4. Demo prompts

• "Draw me a diagram of a typical 3-tier web app: client, API server, database"
• "Diagram a CI/CD pipeline: developer pushes to Git, triggers a build, runs tests, then deploys to staging and production"
• "Show me an event-driven architecture with a producer, a message queue, and two consumers"

Claude will figure out the nodes and edges from your description and call the tool — you're not writing the JSON yourself, that's the point. Open the resulting file at excalidraw.com to show it's a real, editable diagram, not a static image.

Architecture notes

• Why a real Excalidraw file, not just a picture: an LLM could describe a diagram in words, or even generate an SVG. Producing an actual .excalidraw file with correct element bindings means the output is a genuine editable artifact — drag a box, the arrows and label follow. That's a meaningfully different (and harder) target than a static image.
• Layout: intentionally simple (layered left-to-right) rather than a general-purpose graph layout library — sufficient for the kind of system/architecture diagrams this tool is aimed at, and keeps the dependency list at just the MCP SDK.
• Validation: server.py checks that every edge references a real node id before generating anything, returning a clear error instead of producing a broken file.

Repo structure

excalidraw-diagram-agent/
├── README.md
├── requirements.txt
├── layout.py
├── excalidraw_gen.py
├── server.py
└── outputs/   (generated .excalidraw files, gitignored)