+ 发布产品

mcp-excalidraw-server Skill 技能

给 AI 编程 Agent 一块实时 Excalidraw 画布

AI Agent
查看 Skill ↗
认领产品

技能简介

mcp-excalidraw-server 是为 AI 编程 Agent 打造的 Excalidraw 实时画布工作台。它把 Excalidraw 从"一次性绘图小部件"升级为一块 Agent 可编程、可观察、可迭代的持久画布——Claude Code、Codex CLI、Cursor、OpenCode、Google Antigravity 只需一条 npx 即可接入。Agent 在画布上画出架构图、流程图、时序图，然后截图自查修正溢出/重叠/箭头错位，最后把 .excalidraw 文件提交到仓库，让"图随代码走"成为现实。完全本地运行，MIT 协议，无需 API Key。

核心能力

  • 三合一驱动入口：Agent Skill + CLI + 26 个 MCP stdio 工具 + REST API，任意一层都可选用，能力外还打通"无需 MCP 的纯 CLI 流程"。
  • 画布状态完全可控：每个图元都有 create_element / get_element / update_element / delete_element / duplicate_elements 等细粒度工具，支持 query_elements 类型化查询（按 bbox、label、locked 状态过滤）。
  • Agent 视觉自查回路：describe_scene 返回结构化文字摘要，get_canvas_screenshot 返回渲染好的 PNG/SVG，Agent 可以"画→看→改→再看"循环修正，直到标签不溢出、连线不交叉。
  • Headless 渲染（v2.1）：截图与 PNG/SVG 导出不再依赖浏览器标签——Excalidraw 自己的 SVG 导出器在 Node 下跑（jsdom + resvg），未变更的场景 byte-identical 复现，CI / Docker 里直接出图。
  • Mermaid 转换：粘贴 Mermaid 文本直接生成 Excalidraw 流程图，浏览器/多线程场景下与已有画布合并而非覆盖。
  • 布局工具集：align_elements / distribute_elements / group_elements / unlock_elements / lock_elements，支持左对齐/水平均布/分组等版式操作。
  • 快照与回滚：snapshot save/list/restore 服务端命名快照，迭代中可随时回退。
  • Obsidian Vault 集成：导出 .excalidraw.md 格式，文件直接在 Obsidian Excalidraw 插件里打开，block 引用与同步双向兼容。
  • MCP 2026-07-28 协议：支持现代客户端的 server/discover、per-request _meta 信封、无握手调用，同时维持 2025 旧客户端完整可用。

安装配置

  • CLI 一键安装：npx -y mcp-excalidraw-server install-skill --dir 由 Agent 自己选定项目/全局目录，安装可移植 skill 目录。
  • Claude Code 接入：claude mcp add excalidraw --scope user -- npx -y mcp-excalidraw-server。
  • Claude Desktop 配置：在 claude_desktop_config.json 的 mcpServers 添加 npx -y mcp-excalidraw-server 命令。
  • Docker 启动：画布容器 docker run -d -p 3000:3000 ghcr.io/yctimlin/mcp_excalidraw-canvas:latest，MCP stdio 容器用 host.docker.internal 与画布互联。
  • 依赖前置：Node.js ≥ 20；本地 Mermaid 转换与 viewport 操作仍需打开浏览器标签（画布默认 127.0.0.1:3000）。

使用步骤

  1. 首次部署画布：在项目根目录执行 npx -y mcp-excalidraw-server start，画布在 127.0.0.1:3000 启动（绘制命令会自动拉起，无需手动 start）。
  2. 导出 Agent 可读化视觉总结：运行 npx -y mcp-excalidraw-server describe 获取结构化文字摘要；或 screenshot --out /tmp/diagram.png 渲染 PNG。
  3. 绘制一张架构图：把 JSON 描述从 stdin 喂给 add 命令（元素含 id/type/x/y/width/height/text/backgroundColor 与 startElementId/endElementId 标注连线），或通过 MCP 工具 create_element 一次一个。
  4. 自检修正：调用 describe_scene 检查标签/位置，调用 update_element --set '{...}' 修改；query_elements --filter label.text=API 精准查找。
  5. 导出到仓库：执行 export --out docs/architecture.excalidraw，把图作为代码资产提交进 git；下次修改完代码只需 import 重新迭代。
  6. 多 Agent 协同：同一画布允许多个 Agent 同时编辑（WebSocket 实时同步），各自跑不同 sub-graph 最后合并。

适用场景

  • 架构图自动生成：让 Agent 根据代码结构、API 列表、数据库 schema 生成系统架构图、依赖关系图。
  • Onboarding 文档：新成员接入项目时让 Agent 画出模块拓扑、数据管道、调用链路，配合 README 一并发布。
  • 设计评审：Agent 改完代码后自动 screenshot 当前架构图，附在 PR 描述里。
  • 故障复盘：事故复盘时把时序图、状态机图、调用链路图全部交给 Agent 画，配合文字 root cause。
  • CI 中的图同步：CI pipeline 跑 render docs/arch.excalidraw --out docs/arch.png 把图渲染成 PNG 跟文档一起发版。
  • Obsidian Vault 笔记：把架构图/概念图导出 .excalidraw.md 写进 Vault，跨设备同步阅读。
  • 多 Agent 协作设计：让 A Agent 画后端架构、C Agent 画前端状态、D Agent 汇总，三者共享同一画布。

适用人群

  • 后端/全栈工程师：要交付架构设计、API 关系、数据库 ER 图，且希望图随代码 commit。
  • DevOps / SRE：需要把服务依赖图、故障链路画出来作为 runbook 附件。
  • AI 编程 Agent 重度用户：Claude Code / Cursor / Codex CLI 用户，想让 Agent 自动产出图表。
  • 技术写作者与布道师：写技术博客 / 内部 wiki 时需要持续维护的架构图。
  • 产品经理：把用户旅程图、状态机图直接拖进 PRD 附件。
  • 学生 / 教学：计算机系统、数据结构、算法课程的可视化讲义。

工作原理

mcp-excalidraw-server 由两个进程组成一个产品：本地画布服务器（Node + Express + WebSocket + Excalidraw 前端，监听 127.0.0.1:3000）负责画布状态托管与 REST/WebSocket 实时同步；MCP stdio 服务器（基于 @modelcontextprotocol/sdk v2）暴露 26 个工具。两者通过内部 HTTP API 互通。MCP 客户端启动 stdio 服务器时，如果检测到画布未启动就自动 spawn 一个（可通过 EXCALIDRAW_NO_AUTOSTART=1 关闭）。v2.1 引入的 headless 渲染把 Excalidraw 自家的 exportToSvg 跑在 Node 端（jsdom 提供 DOM 仿真），再用 resvg 把 SVG 光栅化为 PNG；输出与浏览器导出像素级一致，未变更场景 byte-identical。MCP 协议支持 2026-07-28（server/discover + _meta 信封）与 2025 legacy（initialize 握手）双向兼容。

官方链接

mcp-excalidraw-server 网站预览

团队信息

AI产品库 官方
由 AI 猎手自动发现

评论与建议

0 条评论