| name | excalidraw-architect |
| description | Choose and compose the right Excalidraw diagram - architecture, flowchart, sequence, state, ER, swimlane, process, timeline, quadrant, pyramid, venn, loop, gantt, bar, line, scatter, and more - using the excalidraw-architect-mcp server. Use whenever a reader would learn more from a picture than from prose, or when asked to draw, diagram, chart, or visualize a system, process, or dataset. |
| license | MIT |
Excalidraw Architect
The MCP server renders. This skill decides what to render and how much.
Picking the wrong diagram type is the most common way a diagram fails. A
cross-functional process drawn as a flowchart loses the handoffs that were the
entire point. A ranking drawn as a bar chart loses the ranking.
1. Before you draw
Ask: would the reader learn more from this than from a well-written
paragraph or a three-column table? If no, write the paragraph.
Don't draw for:
- A list of things → bullets or a table.
- A simple before/after → a two-column table.
- One shape → just write the sentence.
2. The two rules that carry most of the quality
Density target: ~4/10. Enough to be complete, not so dense it needs its
own legend. Above nine nodes it is usually two diagrams — draw an overview
and a detail. Two nodes that always travel together are one node.
Accent is reserved. Every spec accepts "focal": true on its elements.
Mark one or two — the thing you want looked at first. Marking five spends
the signal and leaves the reader with no entry point. Most elements should be
unmarked; that is what makes the marked one work.
A third, quieter rule: every connection should carry information. If the
relationship is already obvious from the layout, delete the line.
3. Picking a type
| If you're showing… | Use | Not when |
|---|
| Components and the connections between them | architecture | (graph type — pass nodes + connections) |
| Decision logic with branches | flowchart | (graph type — pass nodes + connections) |
| Parent -> children: taxonomies, file hierarchies, decision breakdowns. | tree | Use org_chart for people or teams; use nested when containment is the point. |
| Human, team, or agent ownership: reporting lines, escalation, routing. | org_chart | Not for system components -- that is architecture. |
| States, transitions, and guards. Order lifecycles, retry machines, approval flows. | state | Not for time-ordered messages between actors -- that is sequence. |
| Hierarchy by containment or scope: bounded contexts, module trees, org scopes. | nested | Beyond three levels of nesting, split into an overview plus a detail diagram. |
| Stacked abstraction levels where each layer sits on the one below. | layers | If the layers exchange traffic in both directions, use architecture instead. |
| Multi-tier data storage with quality levels: bronze/silver/gold, raw/curated/serving. | medallion | Use data_flow when the emphasis is who does what rather than where data rests. |
| Entities, their fields, and relationships. Data models and schema documentation. | er | Above ~8 entities, split by bounded context. |
| End-to-end stack drawn inside one named boundary (a cluster, an account, a VPC). | high_level | Use architecture when the boundary is not the point. |
| Legacy landscape grouped by phase or department; the 'before' state. | it_state | Use architecture for a target-state design. |
| Cross-functional process where step ownership matters. Handoffs are the story. | swimlane | If every step has the same owner, use flowchart. |
Rules of thumb:
- If a three-column table says the same thing, use the table.
- Combining two types? Pick the dominant axis. Don't hybridize grammars.
- Past the density budget? Split into overview + detail.
4. Calling the tools
list_diagram_types() # the table above, from the server
get_diagram_schema("sequence") # exact spec shape for one type
create_diagram(output_path="./x.excalidraw", diagram_type="sequence", spec={...})
architecture and flowchart are graph types and take nodes +
connections instead of a spec. Everything else takes diagram_type +
spec.
Every spec accepts optional title and subtitle.
Editing. Call get_diagram_info(path) to read the stored spec, then:
modify_diagram(path, [{"op": "update_spec", "patch": {"title": "New title"}}])
The patch is deep-merged. Lists are replaced wholesale — to change one
tier, send the whole tiers list.
Exporting. export_diagram(path, "./x.svg") for SVG; PNG needs the
optional cairosvg extra.
See references/types.md for the full spec shape and a
worked example of every type.
5. Anti-patterns
| Anti-pattern | Why it fails |
|---|
| Accent on five nodes | Destroys the signal it exists to carry. |
| A step drawn across two lanes | Pick one owner; ambiguity is the opposite of the point. |
| A sequence message pointing upward | Reverses time. Never correct. |
| Fifteen nodes in one diagram | Past the budget — split it. |
| A chart with 50 points | Sketchy strokes turn it into a seismograph. Downsample. |
| A table drawn as boxes | Excalidraw has no table primitive. Write the markdown table. |
| Generic labels ("Service A") | Name the real thing or delete the node. |
6. What the renderer already handles
Don't work around these — they are done for you:
- Layout. Never pass coordinates. The engine places and routes everything.
- Chrome vs content. Axes, gridlines, and lane dividers render crisp;
shapes and data marks render hand-drawn. That contrast is deliberate.
- Themes.
default, dark, colorful. Accent and series ramps adapt.
- Bindings. Arrows stay attached when a node is dragged in Excalidraw.
