y
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.
JavaScriptMIT创建于 2025/3/16更新于 今天
README
由 Gemini 翻译整理
Excalidraw MCP Server & Agent Skill
运行实时的 Excalidraw 画布并由 AI Agent 进行控制。本仓库提供：
- MCP Server：通过 Model Context Protocol 连接（Claude Desktop、Cursor、Codex CLI 等）
- Agent Skill：适用于 Claude Code、Codex CLI 及其他支持 Skill 的 Agent 的便携式技能
关键词：Excalidraw agent skill, Excalidraw MCP server, AI 绘图, Claude Code skill, Codex CLI skill, Claude Desktop MCP, Cursor MCP, Mermaid 转 Excalidraw。
演示
AI Agent 仅通过一个提示词即可创建完整的架构图（4倍速）。在 YouTube 上观看完整视频
目录
- 演示
- 这是什么
- 与官方 Excalidraw MCP 的区别
- 最新更新
- 快速开始 (本地)
- 快速开始 (Docker)
- 配置 MCP 客户端
- Agent Skill (可选)
- MCP 工具 (共 26 个)
- 测试
- 故障排查
- 已知问题 / TODO
- 开发
这是什么
本仓库包含两个独立的进程：
- 画布服务器：Web UI + REST API + WebSocket 更新（默认地址
http://localhost:3000） - MCP 服务器：通过 stdio 暴露 MCP 工具；并通过
EXPRESS_SERVER_URL同步到画布
与官方 Excalidraw MCP 的区别
Excalidraw 现已拥有官方 MCP —— 它非常适合在聊天中快速内嵌生成图表。我们解决的是不同的问题。
| 官方 Excalidraw MCP | 本项目 | |
|---|---|---|
| 方法 | 输入提示词，输出图表 (一次性) | 编程级的元素控制 (26 个工具) |
| 状态 | 无状态 —— 每次调用相互独立 | 具有实时同步的持久化动态画布 |
| 元素 CRUD | 无 | 每个元素均可完整的创建/读取/更新/删除 |
| AI 可视化 | 否 | describe_scene (结构化文本) + get_canvas_screenshot (图片) |
| 迭代优化 | 否 —— 需重新生成整个图表 | 绘制 → 查看 → 调整 → 再查看，以元素为单位 |
| 布局工具 | 否 | align_elements, distribute_elements, group / ungroup |
| 文件 I/O | 否 | export_scene / import_scene (.excalidraw JSON) |
| 快照与回滚 | 否 | snapshot_scene / restore_snapshot |
| Mermaid 转换 | 否 | create_from_mermaid |
| 分享链接 | 是 | 是 —— export_to_excalidraw_url |
| 设计指南 | read_me 速查表 | read_diagram_guide (颜色、尺寸、布局、反模式) |
| 视口控制 | 摄像机动画 | set_viewport (缩放以适应、居中元素、手动缩放) |
| 动态画布 UI | 聊天中内嵌渲染 | 通过 WebSocket 同步的独立 Excalidraw 应用 |
| 多 Agent 支持 | 单用户 | 多个 Agent 可在同一画布上同时绘图 |
| 脱离 MCP 使用 | 否 | 是 —— 通过 Agent Skill 提供 REST API 后备支持 |
简而言之 —— 官方 MCP 用于生成图表。我们为 AI Agent 提供了一套完整的画布工具集，用于构建、检查和迭代优化图表 —— 包括让 AI 能看到它们所绘制的内容。
最新更新
v2.0 —— 画布工具集
- 新增 13 个 MCP 工具（共 26 个）：
get_element,clear_canvas,export_scene,import_scene,export_to_image,duplicate_elements,snapshot_scene,restore_snapshot,describe_scene,get_canvas_screenshot,read_diagram_guide,export_to_excalidraw_url,set_viewport - 闭环反馈：AI 现在可以检查画布 (
describe_scene) 并查看它 (get_canvas_screenshot返回图像) —— 从而实现迭代优化 - 设计指南：
read_diagram_guide返回最佳实践的配色方案、尺寸规则、布局模式和反模式 —— 显著提高 AI 生成图表的质量 - 分享链接：
export_to_excalidraw_url对场景进行加密并上传至 excalidraw.com，返回任何人均可打开的分享链接 - 视口控制：通过
set_viewport实现scrollToContent、scrollToElementId或手动缩放/偏移 —— Agent 在创建完成后可自动调整图表视角 - 文件 I/O：导出/导入功能。