Skip to content
Back to search

excalidraw-architect-mcp

Turn your architecture into a living, queryable knowledge graph - and render it as beautiful auto-laid-out Excalidraw diagrams. An MCP server for Cursor, Claude Code & Windsurf. Offline, no API keys.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/bv-venky--excalidraw-architect-mcp/badge.svg)](/listings/bv-venky--excalidraw-architect-mcp)

HTML

<a href="/listings/bv-venky--excalidraw-architect-mcp"><img src="/api/listings/bv-venky--excalidraw-architect-mcp/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Install

pip install excalidraw-architect-mcp

For **PNG export** support (SVG works out of the box):

pip install excalidraw-architect-mcp[png]

Or run without installing (requires [uv](https://docs.astral.sh/uv/)):

uvx excalidraw-architect-mcp

Configure MCP in Your IDE

**Cursor** - Add to `.cursor/mcp.json`:

{
  "mcpServers": {
    "excalidraw-architect": {
      "command": "excalidraw-architect-mcp",
      "transport": "stdio"
    }
  }
}

**Claude Code** - Run this one-liner:

claude mcp add-json excalidraw-architect '{"type":"stdio","command":"excalidraw-architect-mcp"}' --scope user

Or add manually to `.mcp.json` in your project root:

{
  "mcpServers": {
    "excalidraw-architect": {
      "type": "stdio",
      "command": "excalidraw-architect-mcp"
    }
  }
}

**Windsurf / Other IDEs** - Same pattern; point to the `excalidraw-architect-mcp` command over stdio.

Install the Excalidraw Architect Skill (recommended for the 25 types)

[`skills/excalidraw-architect/`](skills/excalidraw-architect/SKILL.md) teaches the AI **which** of the 25 types to pick and how much to put in one — the selection table, the density budget, the reserved-accent rule, and a worked example of every spec.

ln -s "$PWD/skills/excalidraw-architect" ~/.claude/skills/excalidraw-architect

The same guidance also ships inside the server via `list_diagram_types()` and `get_diagram_schema()`, so Cursor, Windsurf, and Zed get it without installing anything — the skill just puts it in context up front instead of one call later. Both are generated from a single source (`src/excalidraw_mcp/diagrams/registry.py`); a test fails the build if they drift.

Install the Diagram Design Skill (recommended)

This repo includes a [Diagram Design Skill](.skills/excalidraw-diagram-design/SKILL.md) that teaches the AI how to structure diagrams for the best results - node count limits, topology rules, edge label guidelines, and common patterns.

**For Cursor users:**

mkdir -p ~/.cursor/skills/excalidraw-diagram-design && \
curl -o ~/.cursor/skills/excalidraw-diagram-design/SKILL.md \
  https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/excalidraw-diagram-design/SKILL.md

**For other IDEs:** Download the [SKILL.md](.skills/excalidraw-diagram-design/SKILL.md) file and add it to your IDE's prompt context or system instructions.

The AI will automatically pick up the skill and apply it when generating diagrams. Feel free to modify the rules to suit your preferences - tweak node limits, add your own patterns, or adjust styling guidelines.

Install the Knowledge Graph Skill (recommended for the graph workflow)

For the [architecture knowledge graph](#-architecture-knowledge-graph), this repo also includes an [Architecture Knowledge Graph Skill](.skills/architecture-knowledge-graph/SKILL.md). It teaches the AI how to read a codebase well — identify service boundaries, map communication signals (HTTP / gRPC / Kafka / DB) to the right labelled links, match producers and consumers across repos, and keep the graph clean (stable ids, every edge labelled, lint before render).

**For Cursor users:**

mkdir -p ~/.cursor/skills/architecture-knowledge-graph && \
curl -o ~/.cursor/skills/architecture-knowledge-graph/SKILL.md \
  https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/architecture-knowledge-graph/SKILL.md

**For other IDEs:** Download the [SKILL.md](.skills/architecture-knowledge-graph/SKILL.md) file and add it to your IDE's prompt context or system instructions.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 424 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Excalidraw Architect MCP
  2. <!-- mcp-name: io.github.BV-Venky/excalidraw-architect-mcp -->
  3. [![PyPI](https://img.shields.io/pypi/v/excalidraw-architect-mcp)](https://pypi.org/project/excalidraw-architect-mcp/)
  4. [![Cursor Directory](https://img.shields.io/badge/Cursor-Directory-purple)](https://cursor.directory/mcp/excalidraw-architect-mcp)
  5. [![License: MIT](https://img.shields.io/badge/License-MIT-green)](LICENSE)
  6. [![PyPI Downloads](https://static.pepy.tech/personalized-badge/excalidraw-architect-mcp?period=total&units=INTERNATIONAL_SYSTEM&left_color=BLACK&right_color=BLUE&left_text=downloads)](https://pepy.tech/projects/excalidraw-architect-mcp)
  7. **Every diagram your engineering docs need — as hand-drawn Excalidraw, generated by your AI.**
  8. Twenty-five diagram types. Architecture and flowcharts, but also sequence diagrams, state machines, ER models, swimlanes, timelines, Gantt charts, quadrants, funnels, and hand-sketched bar/line/scatter charts. No coordinates to hallucinate, no Figma, no stale PNGs.
  9. ## The Problem
  10. When you're onboarding onto a codebase, designing a new system, or documenting how something works, a diagram communicates in seconds what pages of text can't. But the options aren't great.
  11. Mermaid is quick to generate and locked down — you can't drag a node, group things visually, or annotate it afterwards. Figma means thirty minutes of manual work per picture. And when an LLM writes Excalidraw JSON directly it hallucinates coordinates: boxes overlap, arrows tangle, and you fix it by hand.
  12. Worse, most tools only cover *one* diagram type well. The moment your doc needs a sequence diagram next to the architecture sketch, you're switching tools and the two look nothing alike.
  13. ## The Solution
  14. **excalidraw-architect-mcp** separates the *what* from the *where* — the AI describes structure, the engine does the pixel math.
  15. Your LLM says what the components, actors, tiers, or data points are. The MCP picks the layout algorithm for that diagram type, styles it, and writes a real `.excalidraw` file you can open and keep editing. 50+ technologies (Kafka, PostgreSQL, Redis…) get auto-styled, every diagram can be revised in natural language, and it runs fully offline in Cursor/Claude Code/Windsurf — no API keys.
  16. - **25 diagram types, one grammar** — [see them all](#-25-diagram-types), from architecture to Gantt to scatter plots
  17. - **Genuinely hand-drawn output** — a pure-Python port of the roughjs stroke generator, so exported SVG/PNG looks like the Excalidraw canvas, not a clean-geometry approximation
  18. - **Perfect layouts every time** — Sugiyama with adaptive spacing for graphs; purpose-built geometry for everything else
  19. - **Architecture-aware styling** — say "Kafka" and get a stream-styled node, not a generic rectangle
  20. - **Talk to your diagrams** — add, remove, or rewire any diagram in natural language; the spec lives in the file
  21. - **Export to SVG & PNG** — no browser, no Node.js
  22. - **Living architecture knowledge graph** — optionally persist your system as a version-controlled model the AI can query and lint ([details](#-architecture-knowledge-graph))
  23. ## 📐 25 Diagram Types
  24. > Every image below is a real `.excalidraw` file generated by this MCP — zero manual positioning. Click any one to see it full size.
  25. <table>
  26. <tr>
  27. <td align="center" width="33%"><a href="showcase/gallery/architecture.png"><img src="showcase/gallery/architecture.png" alt="Architecture diagram"></a><br><b>Architecture</b><br><sub>Components + connections</sub></td>
  28. <td align="center" width="33%"><a href="showcase/gallery/dp_integration.png"><img src="showcase/gallery/dp_integration.png" alt="DP integration diagram"></a><br><b>DP integration</b><br><sub>Sources → core → consumers</sub></td>
  29. <td align="center" width="33%"><a href="showcase/gallery/sequence.png"><img src="showcase/gallery/sequence.png" alt="Sequence diagram"></a><br><b>Sequence</b><br><sub>Messages over time</sub></td>
  30. </tr>
  31. <tr>
  32. <td align="center" width="33%"><a href="showcase/gallery/timeline.png"><img src="showcase/gallery/timeline.png" alt="Timeline diagram"></a><br><b>Timeline</b><br><sub>Events on an axis</sub></td>
  33. <td align="center" width="33%"><a href="showcase/gallery/gantt.png"><img src="showcase/gallery/gantt.png" alt="Gantt diagram"></a><br><b>Gantt</b><br><sub>Tasks and phases</sub></td>
  34. <td align="center" width="33%"><a href="showcase/gallery/quadrant.png"><img src="showcase/gallery/quadrant.png" alt="Quadrant diagram"></a><br><b>Quadrant</b><br><sub>Two-axis positioning</sub></td>
  35. </tr>
  36. <tr>
  37. <td align="center" width="33%"><a href="showcase/gallery/pyramid.png"><img src="showcase/gallery/pyramid.png" alt="Pyramid / funnel diagram"></a><br><b>Pyramid / funnel</b><br><sub>Ranked tiers or drop-off</sub></td>
  38. <td align="center" width="33%"><a href="showcase/gallery/venn.png"><img src="showcase/gallery/venn.png" alt="Venn diagram"></a><br><b>Venn</b><br><sub>Set overlap</sub></td>
  39. <td align="center" width="33%"><a href="showcase/gallery/loop.png"><img src="showcase/gallery/loop.png" alt="Loop diagram"></a><br><b>Loop</b><br><sub>Flywheel around a hub</sub></td>
  40. </tr>
  41. <tr>
  42. <td align="center" width="33%"><a href="showcase/gallery/bar.png"><img src="showcase/gallery/bar.png" alt="Bar chart diagram"></a><br><b>Bar chart</b><br><sub>Categorical comparison</sub></td>
  43. <td align="center" width="33%"><a href="showcase/gallery/line.png"><img src="showcase/gallery/line.png" alt="Line chart diagram"></a><br><b>Line chart</b><br><sub>Trends over time</sub></td>
  44. <td align="center" width="33%"><a href="showcase/gallery/scatter.png"><img src="showcase/gallery/scatter.png" alt="Scatter plot diagram"></a><br><b>Scatter plot</b><br><sub>Distribution + correlation</sub></td>
  45. </tr>
  46. <tr>
  47. <td align="center" width="33%"><a href="showcase/gallery/nested.png"><img src="showcase/gallery/nested.png" alt="Nested diagram"></a><br><b>Nested</b><br><sub>Hierarchy by containment</sub></td>
  48. <td align="center" width="33%"><a href="showcase/gallery/layers.png"><img src="showcase/gallery/layers.png" alt="Layer stack diagram"></a><br><b>Layer stack</b><br><sub>Stacked abstractions</sub></td>
  49. <td align="center" width="33%"><a href="showcase/gallery/medallion.png"><img src="showcase/gallery/medallion.png" alt="Medallion diagram"></a><br><b>Medallion</b><br><sub>Data quality tiers</sub></td>
  50. </tr>
  51. <tr>
  52. <td align="center" width="33%"><a href="showcase/gallery/er.png"><img src="showcase/gallery/er.png" alt="ER / data model diagram"></a><br><b>ER / data model</b><br><sub>Entities + fields</sub></td>
  53. <td align="center" width="33%"><a href="showcase/gallery/high_level.png"><img src="showcase/gallery/high_level.png" alt="High-level diagram"></a><br><b>High-level</b><br><sub>Stack inside a boundary</sub></td>
  54. <td align="center" width="33%"><a href="showcase/gallery/it_state.png"><img src="showcase/gallery/it_state.png" alt="IT current-state diagram"></a><br><b>IT current-state</b><br><sub>Legacy landscape</sub></td>
  55. </tr>
  56. <tr>
  57. <td align="center" width="33%"><a href="showcase/gallery/swimlane.png"><img src="showcase/gallery/swimlane.png" alt="Swimlane diagram"></a><br><b>Swimlane</b><br><sub>Cross-functional flow</sub></td>
  58. <td align="center" width="33%"><a href="showcase/gallery/process.png"><img src="showcase/gallery/process.png" alt="Process diagram"></a><br><b>Process</b><br><sub>Multi-actor workflow</sub></td>
  59. <td align="center" width="33%"><a href="showcase/gallery/data_flow.png"><img src="showcase/gallery/data_flow.png" alt="Data flow diagram"></a><br><b>Data flow</b><br><sub>Role-scoped pipeline</sub></td>
  60. </tr>
  61. <tr>
  62. <td align="center" width="33%"><a href="showcase/gallery/flowchart.png"><img src="showcase/gallery/flowchart.png" alt="Flowchart diagram"></a><br><b>Flowchart</b><br><sub>Decision logic with branches</sub></td>
  63. <td align="center" width="33%"><a href="showcase/gallery/tree.png"><img src="showcase/gallery/tree.png" alt="Tree diagram"></a><br><b>Tree</b><br><sub>Parent → children</sub></td>
  64. <td align="center" width="33%"><a href="showcase/gallery/org_chart.png"><img src="showcase/gallery/org_chart.png" alt="Org chart diagram"></a><br><b>Org chart</b><br><sub>Ownership + escalation</sub></td>
  65. </tr>
  66. <tr>
  67. <td align="center" width="33%"><a href="showcase/gallery/state.png"><img src="showcase/gallery/state.png" alt="State machine diagram"></a><br><b>State machine</b><br><sub>States + transitions</sub></td>
  68. <td width="33%"></td>
  69. <td width="33%"></td>
  70. </tr>
  71. </table>
  72. ### Choosing and calling
  73. The gallery above is ordered by how often you'll reach for each type. Internally they fall into five families, which is what decides the layout engine:
  74. | Family | Types |
  75. |---|---|
  76. | **Graph** | `architecture` · `flowchart` |
  77. | **Structural** | `tree` · `org_chart` · `state` · `nested` · `layers` · `medallion` · `er` · `high_level` · `it_state` |
  78. | **Flow** | `swimlane` · `process` · `data_flow` · `dp_integration` · `sequence` |
  79. | **Geometric** | `timeline` · `quadrant` · `pyramid` (+ funnel) · `venn` · `loop` · `gantt` |
  80. | **Charts** | `bar` · `line` · `scatter` |
  81. `architecture` and `flowchart` are graphs and take `nodes` + `connections`. Every other type takes a `diagram_type` and a `spec` shaped for it:
  82. ```python
  83. create_diagram(
  84. output_path="./checkout.excalidraw",
  85. diagram_type="sequence",
  86. spec={
  87. "title": "Checkout authorization",
  88. "actors": [{"id": "web", "label": "Web app"}, {"id": "psp", "label": "Payment PSP"}],
  89. "messages": [
  90. {"from_id": "web", "to_id": "psp", "label": "authorize"},
  91. {"from_id": "psp", "to_id": "web", "label": "approved",
  92. "kind": "return", "focal": True},
  93. ],
  94. },
  95. )
  96. ```
  97. Call `list_diagram_types()` for when-to-use guidance on each, and `get_diagram_schema("<type>")` for the exact spec shape. Or just ask: *"draw the PR review flow as a swimlane"*.
  98. **Two conventions worth knowing.** Mark one or two elements `"focal": true` — that earns the accent color, and marking five spends the signal. And chrome (axes, gridlines, lane dividers) deliberately renders crisp while shapes and data marks render hand-drawn; that contrast is what keeps a sketchy chart legible instead of noisy.
  99. **Editing works on every type.** The validated spec is stored inside the `.excalidraw` file, so you patch it rather than rebuild it:
  100. ```python
  101. modify_diagram(path, [{"op": "update_spec", "patch": {"title": "Revised plan"}}])
  102. ```
  103. Lists are replaced wholesale — to change one tier, send the whole `tiers` list.
  104. Regenerate every image above with `python scripts/generate_showcase.py --png`.
  105. ## See It In Action
  106. > Every frame below is generated entirely by AI using this MCP - zero manual positioning.
  107. ### E-Commerce Platform Architecture
  108. ![E-Commerce Platform Demo](showcase/demo_ecommerce.gif)
  109. ### Payment Processing Flow
  110. ![Payment Processing Flow Demo](showcase/demo_payment.gif)
  111. ## Use Cases
  112. - **Onboarding onto a new codebase** — point it at a service and get a high-level architecture diagram without reading a line of code, then a sequence diagram for the one flow that matters.
  113. - **Design docs and RFCs** — an architecture sketch, a state machine for the new lifecycle, a quadrant for the options you rejected, and a Gantt for the rollout. One tool, one visual language.
  114. - **Runbooks and incident write-ups** — sequence diagrams for what happened, timelines for when, swimlanes for who did what.
  115. - **Data platform documentation** — medallion tiers, role-scoped pipelines, integration topology.
  116. - **Reporting without a BI tool** — hand-drawn bar/line/scatter charts that sit next to your architecture diagram instead of clashing with it.
  117. - **Documentation that stays alive** — commit the `.excalidraw` file and revise it in natural language as the system changes. No more stale diagrams from six sprints ago.
  118. ## Quick Start
  119. ### Install
  120. ```bash
  121. pip install excalidraw-architect-mcp
  122. ```
  123. For **PNG export** support (SVG works out of the box):
  124. ```bash
  125. pip install excalidraw-architect-mcp[png]
  126. ```
  127. Or run without installing (requires [uv](https://docs.astral.sh/uv/)):
  128. ```bash
  129. uvx excalidraw-architect-mcp
  130. ```
  131. ### Configure MCP in Your IDE
  132. **Cursor** - Add to `.cursor/mcp.json`:
  133. ```json
  134. {
  135. "mcpServers": {
  136. "excalidraw-architect": {
  137. "command": "excalidraw-architect-mcp",
  138. "transport": "stdio"
  139. }
  140. }
  141. }
  142. ```
  143. **Claude Code** - Run this one-liner:
  144. ```bash
  145. claude mcp add-json excalidraw-architect '{"type":"stdio","command":"excalidraw-architect-mcp"}' --scope user
  146. ```
  147. Or add manually to `.mcp.json` in your project root:
  148. ```json
  149. {
  150. "mcpServers": {
  151. "excalidraw-architect": {
  152. "type": "stdio",
  153. "command": "excalidraw-architect-mcp"
  154. }
  155. }
  156. }
  157. ```
  158. **Windsurf / Other IDEs** - Same pattern; point to the `excalidraw-architect-mcp` command over stdio.
  159. ### Install the Excalidraw Architect Skill (recommended for the 25 types)
  160. [`skills/excalidraw-architect/`](skills/excalidraw-architect/SKILL.md) teaches the AI **which** of the 25 types to pick and how much to put in one — the selection table, the density budget, the reserved-accent rule, and a worked example of every spec.
  161. ```bash
  162. ln -s "$PWD/skills/excalidraw-architect" ~/.claude/skills/excalidraw-architect
  163. ```
  164. The same guidance also ships inside the server via `list_diagram_types()` and `get_diagram_schema()`, so Cursor, Windsurf, and Zed get it without installing anything — the skill just puts it in context up front instead of one call later. Both are generated from a single source (`src/excalidraw_mcp/diagrams/registry.py`); a test fails the build if they drift.
  165. ### Install the Diagram Design Skill (recommended)
  166. This repo includes a [Diagram Design Skill](.skills/excalidraw-diagram-design/SKILL.md) that teaches the AI how to structure diagrams for the best results - node count limits, topology rules, edge label guidelines, and common patterns.
  167. **For Cursor users:**
  168. ```bash
  169. mkdir -p ~/.cursor/skills/excalidraw-diagram-design && \
  170. curl -o ~/.cursor/skills/excalidraw-diagram-design/SKILL.md \
  171. https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/excalidraw-diagram-design/SKILL.md
  172. ```
  173. **For other IDEs:** Download the [SKILL.md](.skills/excalidraw-diagram-design/SKILL.md) file and add it to your IDE's prompt context or system instructions.
  174. The AI will automatically pick up the skill and apply it when generating diagrams. Feel free to modify the rules to suit your preferences - tweak node limits, add your own patterns, or adjust styling guidelines.
  175. ### Install the Knowledge Graph Skill (recommended for the graph workflow)
  176. For the [architecture knowledge graph](#-architecture-knowledge-graph), this repo also includes an [Architecture Knowledge Graph Skill](.skills/architecture-knowledge-graph/SKILL.md). It teaches the AI how to read a codebase well — identify service boundaries, map communication signals (HTTP / gRPC / Kafka / DB) to the right labelled links, match producers and consumers across repos, and keep the graph clean (stable ids, every edge labelled, lint before render).
  177. **For Cursor users:**
  178. ```bash
  179. mkdir -p ~/.cursor/skills/architecture-knowledge-graph && \
  180. curl -o ~/.cursor/skills/architecture-knowledge-graph/SKILL.md \
  181. https://raw.githubusercontent.com/BV-Venky/excalidraw-architect-mcp/main/.skills/architecture-knowledge-graph/SKILL.md
  182. ```
  183. **For other IDEs:** Download the [SKILL.md](.skills/architecture-knowledge-graph/SKILL.md) file and add it to your IDE's prompt context or system instructions.
  184. > **A note on diagram complexity:** As the number of components and connections grows, diagrams inevitably become harder to read - this is true for humans drawing by hand too, not just automated layout. For best results, aim for **6-15 nodes** in architecture diagrams and **10-25 nodes** in detailed flows. If your system is larger, split it into multiple focused diagrams rather than cramming everything into one.
  185. ### Use It
  186. Just ask your AI IDE naturally:
  187. > "Create a high-level architecture diagram of this codebase"
  188. > "Create an architecture diagram for a microservices system with an API Gateway, Auth Service, User Service, Order Service, PostgreSQL, Redis cache, and Kafka event bus"
  189. > "Convert this mermaid diagram to excalidraw diagram"
  190. > "Add a Caching layer to the Order Service in the High Level architecture diagram"
  191. > "Export the architecture diagram to SVG"
  192. > "Export the diagram as a PNG at 3x resolution"
  193. The AI calls the MCP tool with the relationship map. The MCP handles layout, styling, and output. Open the resulting `.excalidraw` file with the [Excalidraw VS Code extension](https://marketplace.visualstudio.com/items?itemName=pomdtr.excalidraw-editor) or drag it into [excalidraw.com](https://excalidraw.com).
  194. ## Features
  195. ### Auto Layout Engine
  196. Uses the Sugiyama hierarchical layout algorithm with:
  197. - **Adaptive layer gaps** - spacing adjusts based on edge label length
  198. - **Hub node stretching** - gateways/load balancers stretch to span connected services
  199. - **Obstacle-aware edge routing** - arrows curve around intermediate nodes instead of cutting through them
  200. - **Disconnected component stacking** - separate subgraphs (e.g., monitoring stack) are placed without overlap
  201. ### Component Library
  202. 50+ technology mappings with automatic visual styling:
  203. | Category | Technologies |
  204. |---|---|
  205. | Database | PostgreSQL, MySQL, MongoDB, DynamoDB, Cassandra, ClickHouse, SQLite, CockroachDB |
  206. | Message Queue | Kafka, RabbitMQ, SQS, Redis Streams, NATS |
  207. | Cache | Redis, Memcached, Varnish |
  208. | Load Balancer | Nginx, HAProxy, ALB/ELB, Traefik, Envoy |
  209. | Compute | Docker, Kubernetes, Lambda, ECS, Fargate |
  210. | Storage | S3, GCS, Azure Blob, MinIO |
  211. | API | REST, GraphQL, gRPC, WebSocket |
  212. | CDN | CloudFront, Cloudflare |
  213. | Monitoring | Prometheus, Grafana, Datadog, ELK |
  214. | Client | Browser, Mobile, Desktop, CLI |
  215. ### Stateful Editing
  216. Diagram metadata is embedded in the `.excalidraw` file. Ask the AI:
  217. > "Add a Redis cache in front of the database in the existing diagram"
  218. The MCP reads the current state, applies the modification, and re-renders with proper layout.
  219. ### Mermaid Conversion
  220. Already have a Mermaid flowchart? Convert it:
  221. > "Convert this Mermaid diagram to Excalidraw" (paste your Mermaid syntax)
  222. ### Image Export That Still Looks Hand-Drawn
  223. Excalidraw's sketchy look is not stored in the file — it is produced at render time by [roughjs](https://roughjs.com), which redraws every shape as two jittered strokes seeded from the element. An exporter that emits a plain `<rect>` reproduces the geometry perfectly and the character not at all.
  224. So this one ports the roughjs stroke generator to Python: same seeded PRNG, same line/curve/ellipse/fill routines. Exports match the canvas — doubled pencil strokes, overshooting circles, V-shaped arrowheads, and fills that sit slightly inside their outlines.
  225. - **SVG** — zero extra dependencies, no browser, no Node.js
  226. - **PNG** — requires the optional `cairosvg` package (`pip install excalidraw-architect-mcp[png]`); configurable resolution multiplier (default 2×)
  227. Chrome renders crisp on purpose. Axes, gridlines, and lane dividers are drawn at `roughness: 0`, because a 1px hairline with hand-drawn jitter is indistinguishable from noise.
  228. **Fonts.** Excalidraw's `Excalifont` is a bundled webfont, so a standalone SVG has nothing to resolve it to. Exports name a stack of real handwriting faces (Excalifont → Virgil → Segoe Print → Bradley Hand → Chalkboard) instead of the generic CSS `cursive`, which on macOS resolves to the calligraphic Apple Chancery. For output that looks identical everywhere, pass a font file to embed it:
  229. ```python
  230. export_to_svg("arch.excalidraw", "arch.svg", embed_font="Excalifont.woff2")
  231. ```
  232. > "Export the architecture diagram as an SVG"
  233. ## MCP Tools
  234. ### Diagram tools
  235. | Tool | Description |
  236. |---|---|
  237. | `create_diagram` | Create a diagram of any of the 25 supported types |
  238. | `list_diagram_types` | Every type with when-to-use / when-not-to guidance |
  239. | `get_diagram_schema` | Spec schema + worked example for one type |
  240. | `mermaid_to_excalidraw` | Convert Mermaid flowchart syntax to `.excalidraw` |
  241. | `modify_diagram` | Patch an existing diagram — nodes/connections, or the stored spec |
  242. | `get_diagram_info` | Read current diagram state (call before modifying) |
  243. | `export_diagram` | Export `.excalidraw` to SVG or PNG image |
  244. ### Knowledge graph tools (`kg_*`)
  245. Optional. For the architecture-documentation workflow only — the knowledge graph (default `.claude/architecture.md`) becomes the source of truth and diagrams become rendered views of it. See [Architecture Knowledge Graph](#-architecture-knowledge-graph) below.
  246. | Tool | Description |
  247. |---|---|
  248. | `kg_init` | Create a new knowledge graph file |
  249. | `kg_add_service` / `kg_remove_service` | Add/update or remove a service (with type, domain, owner, tags, links) |
  250. | `kg_link` / `kg_unlink` | Add/remove a dependency (parallel edges supported — e.g. REST *and* Kafka between the same pair) |
  251. | `kg_set_domain` | Group a service into a domain / bounded context |
  252. | `kg_info` | Summarize services, domains, and topology |
  253. | `kg_render` | Render the whole architecture to `.excalidraw` |
  254. | `kg_render_view` | Render a focused diagram of specific services |
  255. | `kg_render_around` | Render everything within N hops of a service |
  256. | `kg_render_domain` | Render a single domain |
  257. | `kg_import` | Bootstrap the graph from an existing `.excalidraw` diagram |
  258. | `whats_connected_to` | Impact analysis — upstream/downstream blast radius |
  259. | `kg_path` | Trace the dependency path between two services |
  260. | `kg_lint` | Health check: cycles, single points of failure, orphans, dangling refs |
  261. | `kg_export` | Export the graph to Mermaid, Graphviz DOT, or JSON |
  262. | `kg_diff` | Show how the architecture changed since a git ref |
  263. | `kg_onboarding_doc` | Generate a human onboarding guide from the graph |
  264. | `kg_drift` | Detect drift between the declared graph and Python imports |
  265. ## 🧠 Architecture Knowledge Graph
  266. > **Optional, and only for architecture.** Everything above works without it. But if you document one system repeatedly, a one-off diagram goes stale the moment you close it — so architecture diagrams can instead be *views* of a persistent, version-controlled model the AI builds once and reuses everywhere.
  267. ![Knowledge Graph rendered diagram](showcase/knowledge_graph.svg)
  268. > *The diagram above was rendered from a knowledge graph — a single `.claude/architecture.md` file. Notice `Order Service → Payment Service` appears twice: a solid `REST /charge` call and a dashed `Kafka payment.requested` event. Two communication modes, two arrows.*
  269. ### Why a knowledge graph?
  270. A one-off diagram goes stale the moment you close it. A **knowledge graph** is a living model:
  271. - **One source of truth, many views** — store the whole system once, then render the full picture, a single domain, or everything within N hops of one service.
  272. - **Consistent across diagrams** — the same service keeps the same id, styling, and metadata everywhere.
  273. - **Queryable** — ask "what breaks if payments goes down?" and get the real blast radius, not a guess.
  274. - **Self-checking** — lint for dependency cycles, single points of failure, and orphaned services.
  275. - **Lives in git** — review architecture changes in PRs; the markdown diffs cleanly.
  276. ### The file is human- *and* machine-readable
  277. The graph is a single markdown file (default `.claude/architecture.md`):
  278. ```markdown
  279. ## Services
  280. - order-service: Order Service [type: service] [domain: orders] [owner: @orders]
  281. - payment-service: Payment Service [type: service] [domain: payments] [owner: @payments]
  282. ## Dependencies
  283. - order-service -> payment-service : "REST /charge"
  284. - order-service -> payment-service : "Kafka payment.requested" [style: dashed]
  285. ```
  286. Edit it by hand or let the AI maintain it — it round-trips losslessly either way.
  287. ### Just ask your AI
  288. > "Map this codebase into the architecture knowledge graph"
  289. > "Link the order service to payments over Kafka"
  290. > "What depends on the payment service? Render just its neighborhood"
  291. > "Render the orders domain as a focused diagram"
  292. > "Lint the architecture for cycles and single points of failure"
  293. > "Import my existing diagram.excalidraw into the knowledge graph"
  294. > "Generate an onboarding guide from the architecture"
  295. See the [Knowledge Graph tools](#mcp-tools) for the full tool list.
  296. ## Contributing
  297. See [CONTRIBUTING.md](CONTRIBUTING.md) for details.
  298. ## License
  299. MIT - see [LICENSE](LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.