1. 项目概述当白板工具遇上AI架构师如果你和我一样经常在白板上画架构图、流程图然后花大量时间整理成规范的文档那你一定会对这个项目感兴趣。excalidraw-architect-mcp不是一个独立的应用而是一个MCPModel Context Protocol服务器。它的核心价值在于将我们熟悉的、自由手绘风格的 Excalidraw 白板与强大的 AI 助手比如 Claude Desktop无缝连接起来。简单来说它让 AI 助手“看懂”了你的草图。你不再需要费力地向 AI 描述“这里有一个用户通过 API Gateway 访问 Lambda 函数后面连着 DynamoDB...”。你只需要在 Excalidraw 上画出这个草图然后直接问你的 AI 助手“帮我分析一下这个架构的瓶颈在哪里” 或者 “把这个架构图转换成 PlantUML 代码。” 这个 MCP 服务器就是中间的“翻译官”和“执行器”。我最初接触这个项目是因为在团队协作中架构评审经常在白板上进行但后续的文档化、合规检查、成本估算都是繁琐的重复劳动。这个工具的出现相当于给我们的创意和讨论过程装上了一套自动化流水线。它解决的不仅仅是“画图”的问题更是“理解图”、“分析图”和“基于图进行创作”的问题。无论你是架构师、开发者还是产品经理只要你的工作流中涉及可视化设计和系统思考这个工具都能显著提升你的效率。2. 核心原理与MCP协议解析要理解excalidraw-architect-mcp的价值必须先搞懂 MCP 是什么。MCP全称 Model Context Protocol是由 Anthropic 公司提出的一种开放协议。你可以把它想象成 AI 模型的“外设驱动标准”。2.1 MCPAI的“手”和“眼”在没有 MCP 之前像 Claude、ChatGPT 这样的 AI 助手其能力主要局限于文本对话。它们知道很多事情但无法直接操作你的电脑、读取特定格式的文件或与专业软件交互。MCP 协议定义了一套标准允许开发者创建“服务器”Server。这些服务器就像一个个专用的工具包AI 模型可以通过标准的“调用”方式使用这些工具。excalidraw-architect-mcp就是一个这样的工具包服务器。它向 AI 模型如 Claude暴露了几个关键能力读取Read从指定的 Excalidraw 文件.excalidraw或.excalidrawlib中解析出所有图形元素、文字、箭头连接关系。分析Analyze理解这些元素构成的语义比如识别出哪些矩形代表“服务”哪些箭头代表“数据流”哪些图标是“数据库”。转换Transform将 Excalidraw 的图形数据转换成其他格式如 PlantUML、Mermaid、甚至 Markdown 表格形式的架构描述。生成Generate基于对现有图的理解创建新的、符合某种规范或模板的图形元素。当你在 Claude Desktop 中安装了对应的 MCP 服务器后Claude 就“获得”了这些能力。你上传一个 Excalidraw 文件Claude 在背后会通过 MCP 协议调用这个服务器获取文件的结构化信息然后基于这些信息来回答你的问题或执行你的指令。2.2 项目架构拆解这个项目的代码结构清晰地反映了其作为 MCP 服务器的定位excalidraw-architect-mcp/ ├── src/ │ ├── tools/ # 核心工具定义 │ │ ├── analyze.ts # 架构分析工具 │ │ ├── convert.ts # 格式转换工具 │ │ └── ... # 其他工具如生成、验证 │ ├── parsers/ # 解析器 │ │ └── excalidrawParser.ts # 解析.excalidraw JSON结构 │ ├── converters/ # 转换器 │ │ ├── plantUMLConverter.ts │ │ ├── mermaidConverter.ts │ │ └── ... │ └── server.ts # MCP服务器主入口 ├── package.json └── ...核心工作流如下用户指令你在 Claude 中输入“请分析我上传的aws-architecture.excalidraw文件中的安全风险。”MCP调用Claude 识别出这是一个需要调用excalidraw-architect工具的请求通过 MCP 协议向本地运行的excalidraw-architect-mcp服务器发送请求附上文件路径和操作指令analyze_architecture。服务器处理服务器收到请求后启动对应的工具如src/tools/analyze.ts。该工具会调用解析器excalidrawParser读取并解析 JSON 文件。遍历所有图形元素应用一套内置的“语义理解”规则例如包含“DB”文字的矩形可能是数据库红色箭头可能表示错误流。执行安全检查逻辑例如识别出公网可访问的组件是否缺少防火墙、敏感数据是否明文传输。结果返回服务器将分析结果一段结构化的文本报告通过 MCP 协议返回给 Claude。AI整合回复Claude 接收到这份报告结合其自身的知识库组织成一段易于理解的、带有建议的自然语言回复呈现给你。注意MCP 服务器运行在你的本地环境你的 Excalidraw 文件数据不会上传到云端除非你使用的 AI 助手本身有上传功能。这为处理敏感的企业架构图提供了良好的隐私基础。3. 环境配置与实战安装指南理论讲完了我们动手把它跑起来。整个过程可以分为三步配置 Claude Desktop、安装 MCP 服务器、进行连接测试。我会以 macOS 环境为例Windows 和 Linux 用户只需在命令上稍作调整。3.1 前置条件准备首先确保你的系统已经具备以下环境Node.js: 版本 18 或更高。这是运行该 MCP 服务器的基础。可以在终端输入node -v检查。Claude Desktop: 从 Anthropic 官网下载并安装。这是目前最主流的使用 MCP 的客户端。Git: 用于克隆项目代码。一个 Excalidraw 文件用于测试。你可以从 Excalidraw 官网 画一个简单的流程图并导出为.excalidraw文件或者用项目提供的示例文件。3.2 安装 MCP 服务器项目的安装方式非常灵活提供了两种主流方法直接从源码运行或者通过modelcontextprotocol的 CLI 工具安装。方法一源码运行推荐便于调试和自定义克隆项目打开终端找一个合适的目录执行以下命令。git clone https://github.com/BV-Venky/excalidraw-architect-mcp.git cd excalidraw-architect-mcp安装依赖项目使用 TypeScript 开发需要安装依赖包。npm install实操心得如果遇到网络问题可以尝试配置 npm 镜像源npm config set registry https://registry.npmmirror.com。安装完成后建议运行一次npm run build来编译 TypeScript 代码确保没有语法错误。运行服务器你可以直接使用npm start来启动服务器。但更常见的做法是使用npx直接运行编译后的入口文件。查看package.json中的bin字段通常配置了启动命令。方法二使用 MCP CLI 工具安装最简洁Anthropic 提供了一个官方的 MCP 服务器管理工具mcp可以通过它直接安装社区发布的服务器。安装 MCP CLInpm install -g modelcontextprotocol/cli安装 excalidraw-architect 服务器mcp install excalidraw-architect这个命令会自动从 npm 仓库或 GitHub 找到对应的包并进行安装配置。这是最“傻瓜式”的方法适合不想折腾的用户。3.3 配置 Claude Desktop这是最关键的一步告诉 Claude Desktop 去哪里找我们刚刚安装的“工具”。打开Claude Desktop应用。进入配置界面。在 macOS 上点击顶部菜单栏的Claude-Settings...-Developer标签页。在 Windows 上通常在设置或高级选项中。找到MCP Servers配置部分。这里是一个 JSON 数组用于配置多个 MCP 服务器。编辑配置。你需要添加一个如下所示的配置块{ mcpServers: { excalidraw-architect: { command: node, args: [ /ABSOLUTE/PATH/TO/YOUR/excalidraw-architect-mcp/build/index.js ] } } }重要参数解释excalidraw-architect这是你给这个服务器起的名字Claude 内部会引用它。command: node指定用 Node.js 环境来运行这个服务器。args这里的路径必须替换为你本地项目的绝对路径指向编译后的入口文件通常是build/index.js或dist/index.js。如果你使用方法二mcp install安装配置可能会自动生成路径也不同。踩坑记录最大的坑就是路径问题。一定要使用绝对路径。在 macOS/Linux 上可以在终端进入项目build目录输入pwd命令获取完整路径。在 Windows 上右键点击文件“属性”可以查看路径。路径错误会导致 Claude 无法启动服务器在开发者工具的控制台View-Developer-Toggle Developer Tools中可以看到连接失败的报错。保存配置并完全重启 Claude Desktop。仅仅关闭窗口不行需要从任务栏/程序坞彻底退出再重新打开。3.4 验证安装成功重启 Claude 后如何确认工具已经就绪直接询问在 Claude 的聊天框中输入“你现在有哪些可用的工具” 或者 “What tools do you have access to?”。如果配置成功Claude 的回复中应该会列出excalidraw-architect及相关工具例如analyze_excalidraw,convert_to_plantuml等。查看日志启动 Claude 时如果你打开了开发者工具的控制台在Console标签页下可以看到 MCP 服务器初始化的日志如[MCP] Starting server: excalidraw-architect连接成功后会有相应提示。进行测试上传一个简单的.excalidraw文件然后对 Claude 说“请描述一下这个图里画了什么。” 如果 Claude 能够准确说出图中的形状、文字和连接关系而不是让你“上传图片”那就说明 MCP 服务器正在正常工作Claude 已经能“看懂”Excalidraw 文件了。4. 核心功能深度体验与用例解析安装配置只是开始真正的威力在于如何使用。excalidraw-architect-mcp提供了一系列工具我们可以把它们归纳为四大类解析洞察、格式转换、智能生成和架构治理。下面我们结合具体场景看看如何用它来解决实际问题。4.1 场景一从草图到规范文档解析与转换痛点在头脑风暴会议中我们在 Excalidraw 上快速绘制了一个微服务架构草图。会议结束后我需要将其整理成团队知识库要求的 PlantUML 格式并附上一份架构说明文档。传统做法对照草图手动在 PlantUML 编辑器里重新绘制并撰写文档。耗时耗力且容易出错。使用 MCP 的工作流将会议产生的.excalidraw文件保存到本地。在 Claude 中上传该文件。给 Claude 指令“将这张架构图转换为 PlantUML 代码并生成一份 Markdown 格式的架构概述包括服务组件列表、数据流向说明和潜在的单点故障。”Claude 会调用convert_to_plantuml和analyze_architecture工具。几秒钟后你得到两份输出一份可以直接粘贴到 PlantUML 渲染工具中的代码。一份结构清晰的 Markdown 文档。背后的技术细节convert_to_plantuml工具并不是简单地把矩形变成rectangle箭头变成--。它尝试进行语义映射。例如Excalidraw 中一个画了数据库圆柱图标的矩形会被映射为 PlantUML 的database组件。箭头上的文字标签会被转换为-上的注释。工具还会尝试保持图形的相对布局虽然 PlantUML 是自动布局但通过分组和注释可以尽量还原设计意图。4.2 场景二架构评审与风险分析智能分析痛点作为 Tech Lead我需要评审团队提交的架构设计图快速识别出不符合最佳实践或存在安全隐患的设计。传统做法凭经验肉眼扫描在图上做标记然后写评审意见。对于复杂架构容易遗漏。使用 MCP 的工作流收到架构图文件。指令“分析此架构图列出所有面向公网的服务组件检查它们是否都有负载均衡器或防火墙保护。同时识别图中是否存在数据存储组件直接暴露给前端的情况。”Claude 调用analyze_architecture工具并可能结合其自身的网络安全知识。输出一份检查清单例如[风险] 组件 ‘UserAPI’ (矩形) 被标记为‘Public’但未连接到任何负载均衡器图形。[建议] 组件 ‘Frontend’ 直接连接到 ‘Redis Cache’。建议增加一个API层进行隔离。[合规] 所有数据库组件均位于标记为‘Private Subnet’的区域内符合安全规范。工具的能力边界需要注意的是这种分析基于图形元素的文本标签和相对位置。如果设计师没有用“Public”、“DB”等文字标签或者安全组、防火墙是以非标准图形表示的工具可能无法识别。因此它更适合作为辅助审查和提示而非完全自动化的审计工具。团队可以借此约定一些 Excalidraw 绘图规范比如用特定颜色表示网络区域用固定图标表示组件类型从而最大化工具的效用。4.3 场景三快速原型与迭代智能生成痛点我需要为一个新的“文件上传处理管道”设计架构。我从一个基础模板开始但想快速生成几个备选方案如使用 SQS 队列 vs. 使用 Kafka。传统做法复制粘贴基础图然后手动修改组件和连线效率低下。使用 MCP 的工作流准备好一个基础的、包含“用户上传”、“处理服务”、“存储”三个元素的 Excalidraw 文件。指令“基于我上传的草图生成一个引入消息队列用标准队列图标进行异步解耦的变体架构图。请输出新的 Excalidraw JSON 内容。”Claude 调用generate_variant或类似工具如果项目实现了的话理解当前架构的意图并插入一个消息队列组件重新连接箭头。你获得一段新的 Excalidraw JSON 代码。你可以将其保存为.excalidraw文件并打开就得到了一个衍生设计。进阶用法你甚至可以要求“生成三个不同的高可用方案分别基于主动-被动、多活区域和负载均衡器集群。” AI 会利用其对架构模式的知识结合 MCP 工具的图形生成能力快速产出可视化草图极大地加速了设计探索阶段。4.4 场景四架构资产管理与知识沉淀治理与转换痛点公司内有成百上千个历史架构图格式不一Visio, PPT, 图片难以搜索、管理和复用。使用 MCP 的工作流标准化利用convert_to_mermaid工具将所有能转换为 Excalidraw 的架构图统一转换成 Mermaid 文本格式。Mermaid 是文本化的图表语言非常适合用 Git 进行版本管理。建立索引使用analyze_architecture工具批量处理这些图表提取关键元数据如组件类型、技术栈关键词、创建者存入一个简单的数据库或索引文件。智能检索当需要查找“所有使用了 Kafka 和 Redis 的架构”时可以直接询问 Claude“在我们的架构资产库中找出所有包含 Kafka 和 Redis 组件的设计图。” Claude 可以通过调用工具查询索引快速定位相关文件。文档同步当架构图更新后可以自动触发流程重新生成对应的 PlantUML 代码和 Markdown 文档确保知识库的实时性。这个场景将excalidraw-architect-mcp从一个单点工具提升到了架构治理流水线的核心环节。它成为了连接可视化设计、机器可读架构描述和知识库的桥梁。5. 高级技巧与自定义开发指南当你熟悉了基本用法后你可能会不满足于开箱即用的功能。好消息是作为一个开源项目excalidraw-architect-mcp具有很强的可扩展性。你可以根据自己的需求定制分析规则、增加新的转换器甚至集成内部工具。5.1 理解工具定义与扩展点所有 MCP 工具都在src/tools/目录下定义。每个工具都是一个函数接收参数执行逻辑返回结果。我们以analyze_architecture为例看看如何修改。打开src/tools/analyze.ts你会看到类似的结构export const analyzeArchitectureTool: McpTool { name: analyze_architecture, description: Analyzes an Excalidraw file for architectural insights..., inputSchema: { type: object, properties: { filePath: { type: string, description: Path to the .excalidraw file }, analysisType: { type: string, enum: [security, cost, performance, general], description: Type of analysis to perform } }, required: [filePath] }, handler: async (args: any) { const { filePath, analysisType general } args; // 1. 读取并解析文件 const elements await parseExcalidrawFile(filePath); // 2. 根据 analysisType 应用不同的分析规则 const insights []; if (analysisType security) { insights.push(...checkSecurity(elements)); } else if (analysisType cost) { insights.push(...estimateCost(elements)); } // 3. 返回结果 return { content: [{ type: text, text: Analysis Results:\n${insights.join(\n)} }] }; } };自定义分析规则如果你想增加一个“合规性”检查比如检查是否包含了数据隐私声明组件你可以在analysisType的enum中添加compliance。在handler函数中添加对应的else if (analysisType compliance)分支。实现一个checkCompliance(elements)函数遍历图形元素应用你的业务规则。5.2 添加新的输出格式转换器假设你的团队使用C4 Model进行架构设计你需要将 Excalidraw 图转换成Structurizr DSL一种用于 C4 模型的文本语言。创建新转换器在src/converters/目录下新建一个文件structurizrConverter.ts。实现转换逻辑编写一个函数接收解析后的 Excalidraw 元素数组遍历它们识别出人物、软件系统、容器、组件等 C4 元素通常需要依赖约定的图形标签或颜色然后生成对应的 Structurizr DSL 代码字符串。暴露新工具在src/tools/convert.ts中导入你的新转换器并在convertTool的handler函数中增加对新格式如structurizr的支持。重建并重启运行npm run build重新编译项目然后重启 Claude Desktop 使新工具生效。5.3 与企业内部系统集成更强大的用法是将这个 MCP 服务器与你公司的内部系统打通。例如与 CMDB 集成在analyze_architecture工具中当识别出一个 AWS S3 图标时不仅提示这是一个存储服务还可以通过调用内部 CMDB 的 API查询公司实际使用了多少个 S3 Bucket并附上链接。与成本中心集成在成本分析中识别出“EC2”和“RDS”组件后可以调用云成本管理平台的 API获取类似规格资源的月度预估费用使分析报告更具实际指导意义。自动生成工单识别出安全风险后工具可以自动调用 Jira 或 ServiceNow 的 API创建一条“安全加固”待办事项并分配给相应的运维团队。实现这些集成的关键在于你可以在工具的handler函数中自由地引入任何 Node.js 库发起网络请求处理返回数据然后将丰富后的信息返回给 AI。这样Claude 就成为了一个能够调用你整个技术栈能力的超级助手。开发心得在自定义开发时务必做好错误处理。网络请求可能会失败内部 API 的格式可能会变化。在handler函数中使用try...catch并返回清晰的错误信息给 Claude这样用户才能知道问题出在哪里。另外考虑到 MCP 调用可能有超时限制复杂的集成操作最好设计成异步或只返回关键摘要。6. 常见问题、故障排查与优化建议在实际使用和开发扩展的过程中你肯定会遇到各种问题。下面我整理了一些典型问题及其解决方法以及让工具更好用的优化建议。6.1 安装与连接问题问题现象可能原因解决方案Claude 回复“我没有这个功能”或工具列表里没有excalidraw-architect。1. Claude Desktop 配置未生效。2. MCP 服务器路径错误。3. 服务器启动失败。1.彻底重启Claude Desktop完全退出再打开。2. 检查claude_desktop_config.json中的args路径必须为绝对路径。3. 打开 Claude Desktop 的开发者工具Toggle Developer Tools查看Console标签页有无红色错误日志。根据日志排查。开发者工具 Console 中出现[MCP] Server startup failed错误。1. Node.js 版本不兼容。2. 项目依赖未安装或损坏。3. 入口文件不存在。1. 确保 Node.js 18。使用node -v检查。2. 进入项目目录删除node_modules和package-lock.json重新运行npm install。3. 确认build/index.js或dist/index.js文件存在。如果不存在运行npm run build。工具调用超时或无响应。1. 工具处理逻辑太复杂耗时过长。2. 文件路径不存在或权限不足。1. 对于大型 Excalidraw 文件分析可能需要时间。可以尝试优化代码或先处理小文件测试。2. 确保 Claude Desktop 有权限读取你指定的文件路径。6.2 功能使用问题问题现象可能原因解决方案Claude 无法正确识别图中的组件如把数据库说成普通方框。工具依赖文本标签或特定图形库进行语义识别。如果绘图时使用了自由绘制或非标准图标识别率会下降。1.建立绘图规范团队约定使用 Excalidraw 内置的“Library”中的标准图标如“Database”、“Cloud”、“Server”等。2.善用文本标签在图形内部或旁边添加明确的文字标签如“MySQL DB”、“API Gateway”。工具主要靠文字理解意图。3. 向项目提 Issue 或 PR增加对更多图形样式的识别规则。转换生成的 PlantUML/Mermaid 代码布局混乱不符合原图。Excalidraw 是自由画布而 PlantUML/Mermaid 是自动布局引擎。转换器只能尽力映射关系无法完美复现绝对位置。1.接受自动布局将生成的代码视为逻辑关系的准确描述而非视觉复刻。对于演示文档逻辑正确比布局一致更重要。2.手动调整以生成的代码为基础在 PlantUML 编辑器中手动调整布局指令如together-down-等这是最可控的方式。3. 考虑使用 Excalidraw 的“框架”或“分组”功能转换器可能会尝试将这些结构映射为子图或分组。分析报告过于笼统或不准。内置的分析规则相对通用可能不符合你所在领域或公司的特定规范。自定义规则这是开源项目的优势。参考第5章修改src/tools/analyze.ts加入你们团队的检查清单例如“所有外部服务调用必须经过服务网格图标”、“数据存储必须标注加密状态”等。6.3 性能与使用优化建议处理大型文件如果架构图非常复杂元素超过500个解析和转换可能会变慢。建议将大图拆分成多个逻辑相关的子图。在进行分析时通过指令让 Claude 只关注特定部分例如“仅分析图中‘支付模块’区域的组件该区域用蓝色框标出。”结合 AI 提示词工程工具提供了原始数据但最终回复的质量也取决于你如何提问。例如低效提问“分析这个架构。”高效提问“从高可用性、故障隔离和成本优化三个维度分析此架构图。对于每个发现的问题请提供具体的 AWS 或 Azure 服务改进建议。” 后一种提问方式能引导 Claude 结合其庞大的知识库和工具提供的数据给出更具洞察力的答案。建立团队知识库将常用的分析指令、转换模板保存下来。例如可以创建一个文本文件里面包含你们团队标准的架构评审问题列表。每次评审新图时将这个列表粘贴给 Claude让它依次执行确保评审的全面性和一致性。版本控制你的配置和自定义规则如果你对项目进行了自定义开发如新增转换器、分析规则务必将这些更改用 Git 管理起来。这样可以在团队内部分享并随着上游项目的更新而方便地合并。这个项目的魅力在于它打开了一扇门让静态的架构图“活”了起来成为了可查询、可分析、可演化的数字资产。它不能替代架构师的思考和决策但它能极大地压缩从创意到文档、从设计到评审、从现状到优化的中间过程。