Excalidraw Architect Mcp

Excalidraw Architect MCP

为工程文档绘制所需的各种图表——由 AI 生成 Excalidraw 手绘风格图。

支持 25 种图表类型。不仅有架构图和流程图，还有时序图、状态机、ER 模型、泳道图、时间线、甘特图、象限图、漏斗图，以及手绘风格的柱状图、折线图和散点图。不必担心坐标凭空捏造，无需 Figma，也不会有过时的 PNG。

问题所在

无论是开始熟悉一个代码库、设计新系统，还是记录某个功能的工作原理，一张图表都能在几秒钟内传达文字数页也说不清的内容。但现有选择并不理想。

Mermaid 生成速度快，但限制很多——不能拖动节点、直观地对元素分组，也不能事后添加注释。使用 Figma 则每张图都要手动制作 30 分钟。而 LLM 直接编写 Excalidraw JSON 时又会凭空捏造坐标：方框彼此重叠，箭头交错，最后还得手动修正。

更糟的是，大多数工具只能做好一种图表。文档一旦需要在架构草图旁边加一张时序图，你就得切换工具，而且两张图看起来截然不同。

解决方案

excalidraw-architect-mcp 将内容与布局分开——AI 描述结构，引擎负责像素级计算。

你的 LLM 会说明组件、参与者、层级或数据点的内容。MCP 会为对应图表类型选择布局算法、设置样式，并生成可打开和继续编辑的 .excalidraw 文件。50 多种技术（Kafka、PostgreSQL、Redis 等）会自动应用对应样式，每张图都能通过自然语言修改，而且可在 Cursor/Claude Code/Windsurf 中完全离线运行——无需 API 密钥。

• 25 种图表类型，一套语法——查看全部类型，从架构图到甘特图、散点图
• 真正的手绘风格输出——纯 Python 移植版 roughjs 笔触生成器，让导出的 SVG/PNG 看起来与 Excalidraw 画布一致，而非只是几何形状的近似效果
• 每次都能完美布局——图结构使用带自适应间距的 Sugiyama 算法；其他类型则使用专门设计的几何布局
• 了解架构的样式——说出“Kafka”，得到的就是流式风格节点，而非普通矩形
• 与图表对话——用自然语言添加、删除或重新连接任意图表元素；规范保存在文件中
• 导出为 SVG 和 PNG——无需浏览器或 Node.js
• 动态架构知识图谱——可选地将系统持久化为受版本控制的模型，供 AI 查询和检查（详情）

📐 25 种图表类型

以下每张图片都是此 MCP 生成的真实 .excalidraw 文件——无需手动定位。点击任意图片即可查看大图。

架构 组件 + 连接	DP 集成 来源 → 核心 → 使用方	时序 随时间变化的消息
时间线 坐标轴上的事件	甘特图 任务和阶段	象限图 双轴定位
金字塔 / 漏斗图 分级层次或逐步流失	维恩图 集合重叠	循环图 围绕中心枢纽的飞轮
条形图 类别比较	折线图 随时间变化的趋势	散点图 分布 + 相关性
嵌套图 按包含关系呈现层级	分层堆栈 堆叠的抽象层	奖章图 数据质量层级
ER / 数据模型 实体 + 字段	高层级 边界内的技术栈	IT 当前状态 遗留系统全貌
泳道图 跨职能流程	流程 多参与方工作流	数据流 按角色划分范围的数据管道
流程图 带分支的决策逻辑	树形图 父级 → 子级	组织结构图 职责归属 + 逐级上报
状态机 状态 + 转换

### 选择与调用

上方的图表库按各类型的使用频率排序。它们在内部属于五个类别，而类别决定了布局引擎：

类别	类型
图形	architecture · flowchart
结构	tree · org_chart · state · nested · layers · medallion · er · high_level · it_state
流程	swimlane · process · data_flow · dp_integration · sequence
几何	timeline · quadrant · pyramid（+ funnel） · venn · loop · gantt
图表	bar · line · scatter

architecture 和 flowchart 属于图形，使用 nodes + connections。其他类型都需要 diagram_type 和对应格式的 spec：

create_diagram(
    output_path="./checkout.excalidraw",
    diagram_type="sequence",
    spec={
        "title": "Checkout authorization",
        "actors": [{"id": "web", "label": "Web app"}, {"id": "psp", "label": "Payment PSP"}],
        "messages": [
            {"from_id": "web", "to_id": "psp", "label": "authorize"},
            {"from_id": "psp", "to_id": "web", "label": "approved",
             "kind": "return", "focal": True},
        ],
    },
)

调用 list_diagram_types() 获取各类型的适用场景指南，调用 get_diagram_schema("<type>") 查看确切的 spec 格式。或者直接提出需求：“用泳道图绘制 PR 评审流程”。

有两条约定值得了解。 将一两个元素标记为 "focal": true，即可使用强调色；标记五个元素就会削弱强调效果。图表装饰元素（坐标轴、网格线、泳道分隔线）会以清晰利落的风格呈现，而形状和数据标记则采用手绘风格；这种对比能让草图风格的图表保持易读，而不显杂乱。

所有类型都支持编辑。 经过验证的 spec 会存储在 .excalidraw 文件中，因此只需修改它，而不是重新构建：

modify_diagram(path, [{"op": "update_spec", "patch": {"title": "Revised plan"}}])

列表会被整体替换——要更改某个层级，请发送完整的 tiers 列表。

使用 python scripts/generate_showcase.py --png 重新生成上方所有图片。

实际效果

下方每个画面都完全由 AI 使用此 MCP 生成，无需手动调整位置。

电商平台架构

支付处理流程

使用场景

• 熟悉新的代码库 — 指定一个服务，无需阅读任何代码行即可获得高层架构图，然后为关键流程绘制序列图。
• 设计文档和 RFC — 绘制架构草图、新生命周期的状态机、被否决方案的象限图，以及发布计划的甘特图。一个工具，一套视觉语言。
• 运行手册和事故复盘 — 用序列图说明发生了什么，用时间线标注发生时间，用泳道图展示各方所做的工作。
• 数据平台文档 — 展示 medallion 层级、按角色划分范围的数据管道和集成拓扑。
• 无需 BI 工具的报告 — 手绘风格的柱状图、折线图和散点图，可与架构图并排展示，风格协调一致。
• 持续更新的文档 — 提交 .excalidraw 文件，并在系统变化时用自然语言修改。再也不用面对六个迭代之前就已过时的图表。

快速开始

安装

pip install excalidraw-architect-mcp

如需支持 PNG 导出（开箱即用支持 SVG）：

pip install excalidraw-architect-mcp[png]

也可以不安装直接运行（需要 uv）：

uvx excalidraw-architect-mcp

在 IDE 中配置 MCP

Cursor — 添加到 .cursor/mcp.json：

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

Claude Code — 运行这条单行命令：

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

也可以手动添加到项目根目录下的 .mcp.json：

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

Windsurf / 其他 IDE — 配置方式相同；通过 stdio 调用 excalidraw-architect-mcp 命令即可。

安装 Excalidraw Architect Skill（推荐用于 25 种类型）

skills/excalidraw-architect/ 会指导 AI 选择 25 种类型中的哪一种，以及每张图应包含多少内容——包括选择表、密度预算、强调色保留规则，以及每种 spec 的完整示例。

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

同样的指南也集成在服务中，可通过 list_diagram_types() 和 get_diagram_schema() 获取，因此 Cursor、Windsurf 和 Zed 无需安装任何内容即可使用——Skill 只是提前将指南放入上下文中，而不是等到后续调用时再提供。两者都由同一个源文件（src/excalidraw_mcp/diagrams/registry.py）生成；如果两者不一致，测试会导致构建失败。

安装 Diagram Design Skill（推荐）

此仓库包含一个 Diagram Design Skill，用于指导 AI 如何构建效果最佳的图表——包括节点数量限制、拓扑规则、边标签指南和常见模式。

Cursor 用户：

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

**其他 IDE 用户：**下载 SKILL.md 文件，并将其添加到 IDE 的提示词上下文或系统指令中。

AI 会自动识别该 Skill，并在生成图表时应用其中的规则。你可以根据偏好修改规则——调整节点数量限制、添加自定义模式，或修改样式指南。

安装 Knowledge Graph Skill（图谱工作流推荐）

对于架构知识图谱，此仓库还包含一个 Architecture Knowledge Graph Skill。它会指导 AI 如何更好地读取代码库——识别服务边界，将通信信号（HTTP / gRPC / Kafka / DB）映射到合适的带标签链接，跨仓库匹配生产者和消费者，并保持图谱整洁（稳定的 id、每条边都有标签、渲染前先运行 lint）。

Cursor 用户：

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

**其他 IDE 用户：**下载 SKILL.md 文件，并将其添加到 IDE 的提示词上下文或系统指令中。

**关于图表复杂度的说明：**随着组件和连接数量增加，图表必然会变得更难阅读——这对手工绘图的人员也一样，不只是自动布局的局限。为获得最佳效果，架构图建议包含 6-15 个节点，详细流程图建议包含 10-25 个节点。如果系统规模更大，请将其拆分成多个重点明确的图表，而不是把所有内容都塞进一张图。

使用方法

只需自然地向你的 AI IDE 提出要求：

“为此代码库创建一张高层架构图”

“为一个包含 API Gateway、Auth Service、User Service、Order Service、PostgreSQL、Redis cache 和 Kafka event bus 的微服务系统创建架构图”

“将此 mermaid 图转换为 excalidraw 图”

“在高层架构图的 Order Service 中添加 Caching layer”

“将架构图导出为 SVG”

“将图表以 3x 分辨率导出为 PNG”

AI 会携带关系映射调用 MCP 工具。MCP 负责布局、样式和输出。使用 Excalidraw VS Code extension 打开生成的 .excalidraw 文件，或将其拖入 excalidraw.com。

功能

自动布局引擎

使用 Sugiyama 分层布局算法，具有以下功能：

• 自适应层间距 - 根据边标签长度调整间距
• 枢纽节点延展 - 网关／负载均衡器会延展，以覆盖所连接的服务
• 避障边路由 - 箭头会绕过中间节点弯曲，而不是穿过它们
• 不连通组件堆叠 - 将独立子图（例如监控栈）分开放置，避免重叠

组件库

支持 50 多种技术映射，并可自动应用视觉样式：

类别	技术
数据库	PostgreSQL、MySQL、MongoDB、DynamoDB、Cassandra、ClickHouse、SQLite、CockroachDB
消息队列	Kafka、RabbitMQ、SQS、Redis Streams、NATS
缓存	Redis、Memcached、Varnish
负载均衡器	Nginx、HAProxy、ALB/ELB、Traefik、Envoy
计算	Docker、Kubernetes、Lambda、ECS、Fargate
存储	S3、GCS、Azure Blob、MinIO
API	REST、GraphQL、gRPC、WebSocket
CDN	CloudFront、Cloudflare
监控	Prometheus、Grafana、Datadog、ELK
客户端	浏览器、移动端、桌面端、CLI

有状态编辑

图表元数据嵌入在 .excalidraw 文件中。向 AI 提问：

“在现有图表的数据库前添加一个 Redis 缓存”

MCP 会读取当前状态、应用修改，并以恰当的布局重新渲染。

Mermaid 转换

已经有 Mermaid 流程图？将其转换：

“将此 Mermaid 图表转换为 Excalidraw”（粘贴 Mermaid 语法）

导出图像，同时保留手绘效果

Excalidraw 的手绘风格并未存储在文件中，而是在渲染时由 roughjs 生成。它会根据元素的种子值，将每个形状重新绘制为两条带抖动的笔画。仅输出普通 <rect> 的导出器能完美复现几何形状，却完全无法还原其风格。

因此，这个工具将 roughjs 的笔画生成器移植到了 Python：使用相同的带种子伪随机数生成器，以及相同的直线、曲线、椭圆和填充绘制例程。导出结果与画布一致——双重铅笔笔画、超出边缘的圆形、V 形箭头，以及略微缩进轮廓的填充。

• SVG — 无需额外依赖、浏览器或 Node.js
• PNG — 需要可选的 cairosvg 包（pip install excalidraw-architect-mcp[png]）；可配置分辨率倍率（默认为 2×）

Chrome 有意以清晰的方式渲染。坐标轴、网格线和泳道分隔线的 roughness 均设为 0，因为 1px 的细线加上手绘抖动后，看起来就和噪声无异。

字体。 Excalidraw 的 Excalifont 是内置的 Web 字体，因此独立 SVG 无法解析并使用它。导出结果会指定一组真实的手写字体（Excalifont → Virgil → Segoe Print → Bradley Hand → Chalkboard），而不是通用 CSS 字体 cursive；在 macOS 上，该字体会解析为书法字体 Apple Chancery。要让输出在所有环境中看起来完全一致，请传入字体文件以将其嵌入：

export_to_svg("arch.excalidraw", "arch.svg", embed_font="Excalifont.woff2")

“将架构图导出为 SVG”

MCP 工具

图表工具

工具	描述
create_diagram	创建任意一种受支持的 25 种类型的图表
list_diagram_types	列出所有类型，并提供适用与不适用场景的指导
get_diagram_schema	获取一种类型的规范架构和完整示例
mermaid_to_excalidraw	将 Mermaid 流程图语法转换为 .excalidraw
modify_diagram	修改现有图表——节点/连接，或已存储的规范
get_diagram_info	读取当前图表状态（修改前调用）
export_diagram	将 .excalidraw 导出为 SVG 或 PNG 图像

知识图谱工具（kg_*）

可选。仅用于架构文档工作流——知识图谱（默认文件为 .claude/architecture.md）将成为事实来源，图表则成为它的渲染视图。请参阅下文的架构知识图谱。

工具	描述
kg_init	创建新的知识图谱文件
kg_add_service / kg_remove_service	添加/更新或移除服务（包含类型、领域、负责人、标签和链接）
kg_link / kg_unlink	添加/移除依赖关系（支持平行边——例如同一对服务之间同时存在 REST 和 Kafka）
kg_set_domain	将服务归入某个领域 / 限界上下文
kg_info	汇总服务、领域和拓扑结构
kg_render	将整个架构渲染为 .excalidraw
kg_render_view	渲染特定服务的局部图表
kg_render_around	渲染某个服务 N 跳范围内的所有内容
kg_render_domain	渲染单个领域
kg_import	从现有 .excalidraw 图表初始化图谱
whats_connected_to	影响分析——分析上游/下游的影响范围
kg_path	追踪两个服务之间的依赖路径
kg_lint	健康检查：循环、单点故障、孤立服务或悬空引用
kg_export	将图谱导出为 Mermaid、Graphviz DOT 或 JSON
kg_diff	显示架构自某个 git 引用以来的变化
kg_onboarding_doc	根据图谱生成面向新人的指南
kg_drift	检测声明的图谱与 Python 导入之间的偏差

🧠 架构知识图谱

可选，且仅用于架构。 上述所有功能无需知识图谱也能使用。但如果你要反复记录某个系统，临时图表一关闭就会过时——因此，架构图表可以作为持久化、受版本控制的模型视图，由 AI 一次构建并在各处重复使用。

上图由知识图谱渲染而成，知识图谱存储在单个 .claude/architecture.md 文件中。注意，Order Service → Payment Service 出现了两次：一条实线表示 REST /charge 调用，一条虚线表示 Kafka payment.requested 事件。两种通信方式，两条箭头。

为什么要使用知识图谱？

临时图表一关闭就会过时。知识图谱是一个持续更新的模型：

• 单一事实来源，多种视图——只需存储一次整个系统，即可渲染全貌、单个领域，或某个服务 N 跳范围内的所有内容。
• 图表之间保持一致——同一服务在各处都使用相同的 ID、样式和元数据。
• 可查询——询问“支付服务宕机会造成什么影响？”，即可获得真实的影响范围，而非猜测。
• 自检——检查依赖循环、单点故障和孤立服务。
• 纳入 Git 管理——在 PR 中审查架构变更；Markdown 差异清晰易读。

文件既方便人阅读，也方便机器读取

图谱是一个 Markdown 文件（默认文件为 .claude/architecture.md）：

## Services
- order-service: Order Service [type: service] [domain: orders] [owner: @orders]
- payment-service: Payment Service [type: service] [domain: payments] [owner: @payments]

## Dependencies
- order-service -> payment-service : "REST /charge"
- order-service -> payment-service : "Kafka payment.requested" [style: dashed]

你可以手动编辑，也可以让 AI 维护——无论采用哪种方式，往返转换都不会丢失信息。

直接向 AI 提问

“将此代码库映射到架构知识图谱中”

“通过 Kafka 将订单服务连接到支付服务”

“哪些服务依赖支付服务？只渲染它周边的图表”

“将订单领域渲染为局部图表”

“检查架构中是否存在循环和单点故障”

“将我现有的 diagram.excalidraw 导入知识图谱”

“根据架构生成一份入门指南”

完整工具列表请参阅知识图谱工具。

贡献

详情请参阅 CONTRIBUTING.md。

许可证

MIT - 请参阅 LICENSE。