Excalidraw Architect MCP

在理解陌生且复杂的代码库时，我们常常面临持续的挑战——既要管理认知负荷，又要试图想象各部分是如何组合在一起的。

问题所在

当你入职新项目、设计新系统或记录现有架构时，一张可视化图表能在几秒钟内传达出大段文字无法表达的信息。但目前的方案并不理想。Mermaid 图表生成很快，但功能有限——你无法拖动节点来重新定位，也无法在视觉上对组件进行分组。Excalidraw 解决了这些问题，但当 LLM 尝试直接生成 Excalidraw 时，它们会产生坐标幻觉——方框重叠、箭头缠绕，最终你不得不手动修复图表。

Related MCP server: Excalidraw MCP App

解决方案

excalidraw-architect-mcp 将“内容”与“位置”分离开来——AI 专注于结构，而引擎负责处理像素计算。

你的 LLM 负责描述组件和连接，而 MCP 使用专业的图布局算法来处理布局、样式和渲染。50 多种技术（Kafka、PostgreSQL、Redis 等）可自动应用样式，你可以使用自然语言迭代编辑图表（例如“在数据库前添加一个缓存”），并且它可以在 Cursor/Windsurf 中完全离线运行——无需 API 密钥。

• 每次都能获得完美的布局 - 采用 Sugiyama 算法及自适应间距；无重叠方框

• 架构感知样式 - 说出“Kafka”即可获得流式样式的节点，而不是通用的矩形

• 与你的图表对话 - 使用自然语言在现有图表上添加、删除或重新连接组件

• 中心节点可视化 - 网关和负载均衡器会自动拉伸以跨越其连接的服务

• 导出为 SVG 和 PNG - 将任何 .excalidraw 文件转换为便携式图像，无需浏览器

查看实际效果

下面的每一帧完全由 AI 使用此 MCP 生成——无需任何手动定位。

电子商务平台架构

支付处理流程

使用场景

• 入职新代码库 - 指向一个微服务，无需阅读一行代码即可获得高层架构图。当你需要细节时，将其指向一组类以获取低层流程图。

• 头脑风暴和系统设计 - 当你在白板上设计新服务或讨论权衡时，要求它实时可视化架构。通过说“在这里加个缓存”或“把 Kafka 换成 SQS”来进行迭代，而不是从头开始重绘。

• 保持活力的文档 - 将 .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 命令。

安装图表设计技能（推荐）

此仓库包含一个 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 会自动获取该技能并在生成图表时应用它。请随意修改规则以适应你的偏好——调整节点限制、添加你自己的模式或调整样式指南。

关于图表复杂性的说明： 随着组件和连接数量的增加，图表不可避免地变得难以阅读——这对于人类手绘图表也是如此，不仅仅是自动化布局。为了获得最佳效果，架构图的目标应为 6-15 个节点，详细流程图的目标应为 10-25 个节点。如果你的系统规模更大，请将其拆分为多个重点图表，而不是将所有内容挤在一起。

使用方法

只需自然地询问你的 AI IDE：

"Create a high-level architecture diagram of this codebase"

"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"

"Convert this mermaid diagram to excalidraw diagram"

"Add a Caching layer to the Order Service in the High Level architecture diagram"

"Export the architecture diagram to SVG"

"Export the diagram as a PNG at 3x resolution"

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

功能特性

自动布局引擎

使用 Sugiyama 分层布局算法，具有：

• 自适应层间距 - 间距根据边缘标签长度进行调整

• 中心节点拉伸 - 网关/负载均衡器拉伸以跨越连接的服务

• 障碍感知边缘路由 - 箭头绕过中间节点，而不是穿过它们

• 断开组件堆叠 - 独立的子图（例如监控堆栈）被放置在不重叠的位置

组件库

50 多种技术映射，具有自动视觉样式：

状态化编辑

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

"Add a Redis cache in front of the database in the existing diagram"

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

Mermaid 转换

已经有了 Mermaid 流程图？转换它：

"Convert this Mermaid diagram to Excalidraw" (粘贴你的 Mermaid 语法)

图像导出

将任何 .excalidraw 图表导出为便携式图像——无需浏览器、Excalidraw 应用或 Node.js。

• SVG - 零额外依赖；使用纯 Python 渲染器，处理矩形、椭圆、菱形、文本（包括多行）和带箭头的箭头

• PNG - 需要可选的 cairosvg 包 (pip install excalidraw-architect-mcp[png])；支持可配置的分辨率乘数（默认为 2×）

"Export the architecture diagram as an SVG"

MCP 工具

贡献

详情请参阅 CONTRIBUTING.md。

许可证

MIT - 详见 LICENSE。