yctimlin/mcp_excalidraw

MCP server and Claude Code skill for Excalidraw — programmatic canvas toolkit to create, edit, and export diagrams via AI agents with real-time canvas sync.

功能简介

mcp‑excalidraw‑server 将 Excalidraw 画布转变为一个可编程工作台，AI 编码代理（Claude Code、Cursor、Codex CLI 等）可以驱动它。代理可以：

通过 JSON 命令创建、读取、更新、删除单个图表元素。
实时截取画布截图（现在在 Node 中无头渲染，无需浏览器）。
迭代优化图表：绘制 → 描述 → 截图 → 调整 → 重复。
将结果导出为原生 .excalidraw 文件（或兼容 Obsidian 的 .excalidraw.md），可与代码一起进行版本控制。
导入、合并 Mermaid 图表，分享加密 URL，并拍摄命名快照。

所有这些都通过三种可互换的接口提供：

CLI（npx -y mcp-excalidraw-server <command>），代理推荐使用的方式。
MCP 服务器，支持模型上下文协议（MCP 2026‑07‑28），适用于任何兼容 MCP 的客户端。
REST API，适用于 LangChain 或自定义 HTTP 调用者。

实际绘图在本地 Node ≥ 20 进程中完成；无需外部 API 密钥。

适用人群

编码助手，需要在开发工作流中生成架构图、流程图或 UI 线框图。
CI 流水线，在源代码更改时自动渲染更新的图表。
文档流水线（例如 Obsidian 库），保持视觉资产与代码同步。
团队，希望拥有一个共享的实时画布，多个代理可以并发编辑。

快速开始

# 一行命令：启动画布并观看（可选）
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000   # 在浏览器中查看 UI

# 通过 JSON 绘制两个框和一个箭头
cat <<EOF | npx -y mcp-excalidraw-server add
[
  {"id":"api","type":"rectangle","x":100,"y":100,"width":160,"height":80,"text":"API Server","backgroundColor":"#a5d8ff"},
  {"id":"db","type":"rectangle","x":400,"y":100,"width":160,"height":80,"text":"Database","backgroundColor":"#99e9f2"},
  {"type":"arrow","startElementId":"api","endElementId":"db","text":"SQL"}
]
EOF

# 让代理查看图表并捕获 PNG
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png

# 将图表保存为仓库工件
npx -y mcp-excalidraw-server export --out docs/arch.excalidraw

同样的命令也可以在 Docker 容器内或从源码 npm ci 后运行。

主要特性一览

特性	提供的能力
CLI 优先设计	所有画布操作都是可组合的 JSON 命令；退出码使脚本编写变得容易。
MCP 兼容性	使用最新的 MCP 协议（无需握手），适用于 Claude Desktop、Cursor、Codex CLI、Antigravity 等。
无头渲染	截图和图像导出在 Node 中通过 jsdom + resvg 生成——快速、确定性、适合 CI。
确定性导出	未更改的场景生成字节相同的 `.excalidraw` 文件 → 无嘈杂的 git 差异。
Obsidian 支持	导出为 `.excalidraw.md` 以用于 Obsidian Excalidraw 插件，保留块引用。
Mermaid 导入	将 Mermaid 文本转换为实时 Excalidraw 元素，并与现有内容合并。
快照系统	命名保存/恢复点让代理可以回滚或分支图表状态。
布局工具	对齐、分布、分组/取消分组、锁定、复制——全部通过 MCP 工具或 CLI 标志实现。
可分享 URL	可选加密上传到 excalidraw.com，便于分享。
零配置启动	第一个绘图命令自动启动画布服务器；设置 `EXCALIDRAW_NO_AUTOSTART=1` 可禁用。

限制 / 注意事项

服务器默认仅绑定到 127.0.0.1；外部访问需要您自己的网络防火墙——API 没有内置认证。
某些命令（mermaid 转换、使用 --renderer browser 的截图）仍需要打开实际的浏览器标签页。
需要 Node ≥ 20；不支持旧版本。
字体覆盖仅限于捆绑的 TTF；特殊脚本回退到主机操作系统字体。

许可证与社区

MIT 许可证 – 免费用于商业和个人用途。
在 npm 上发布为 mcp-excalidraw-server（徽章显示当前版本）。
CI 徽章表示自动化测试和 Docker 构建。
欢迎贡献；仓库包含 CONTRIBUTING 风格指南和用于从源码构建的 development 部分。

快速总结

mcp-excalidraw-server 是一个本地运行、CLI 驱动的 Excalidraw 画布，AI 编码代理可以将其视为可变的绘图表面。它提供元素级 CRUD、无头截图、确定性导出以及完整的 MCP/REST 集成，使得直接从 AI 工作流生成、优化和版本控制图表变得容易。