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 等）操作。画布完全在本地运行（Node ≥ 20，无需 API 密钥），可通过以下三种方式访问：
- CLI –
npx -y mcp-excalidraw-server <command>– 一组基于 JSON 的命令，可自动启动画布、添加/更新/删除元素、截取屏幕截图、导出文件等。 - MCP 服务器 – 一个暴露 26 个工具的 Model Context Protocol (MCP) stdio 服务器，任何兼容 MCP 的客户端都可以直接调用绘图操作。
- REST API – 面向 LangChain 等框架的普通 HTTP/WebSocket 端点。
最终结果是一个实时、可编辑的图表，代理可以（通过 describe 或截图）检查它，逐元素进行修改，最后将其导出为 .excalidraw 文件，该文件可以放在源代码旁边或 Obsidian 库中。
适合谁使用
- 编码助手 – 需要在开发工作流中生成架构图、流程图或 UI 线框图的工具。
- 团队 – 希望将图表文件与代码一起进行版本控制的团队（例如，将
.excalidraw文件提交到 Git）。 - Obsidian 用户 – 希望将图表保存在库中并保持完全可编辑性的用户。
- 构建自定义 AI 代理工具链的人 – 构建可以调用 MCP 工具或 REST API 的工具链的开发者。
主要功能（摘自 README）
| 功能 | 说明 |
|---|---|
| 本地画布服务器 | 在 http://127.0.0.1:3000 上运行 Excalidraw Web UI，并提供实时 WebSocket 同步。无需外部服务。 |
| CLI 优先设计 | 所有功能都作为可组合的命令（add、apply、query、screenshot、export、mermaid、snapshot、arrange、share 等）公开。JSON 输出到标准输出，退出代码表示成功/失败。 |
| MCP 集成 | 实现 MCP 协议修订版 2026-07-28。26 个工具让任何 MCP 客户端（Claude Desktop、Cursor、Codex CLI、Antigravity 等）都能通过 stdio 操作画布。 |
| REST API | 面向 LangChain 和自定义脚本的简单 HTTP 端点。 |
| 元素级 CRUD | 可以创建、读取、更新、删除单个形状、箭头、文本、组、锁等。 |
| 迭代优化 | 代理可以 describe 场景、拍摄 screenshot、调整布局，并重复直到图表完成。 |
| 导出 / 导入 | 导出为原生 .excalidraw JSON 或 Obsidian 兼容的 .excalidraw.md。支持导入两种格式，包括压缩文件。 |
| 确定性导出 | ID、种子和键的顺序是稳定的，因此未更改的图表会生成相同的文件，不会产生杂乱的 Git 差异。 |
| Mermaid 转换 | 粘贴 Mermaid 语法，生成的图表会合并到现有画布中。 |
| 视口控制 | 缩放、平移或适配所选元素的命令。 |
| 分享 | 可选地将加密上传到 excalidraw.com 以生成可分享的 URL。 |
| Docker 镜像 | 用于轻松部署的预构建容器（ghcr.io/yctimlin/mcp_excalidraw）。 |
| 代理技能包 | 一个可移植的技能（skills/excalidraw-skill/），可通过单个 install-skill 命令安装到代理的技能目录中。 |
| 零设置自动启动 | CLI 命令和 MCP 服务器会在画布未运行时自动启动（可通过 EXCALIDRAW_NO_AUTOSTART=1 禁用）。 |
快速开始
# 安装并启动画布（在第一个绘图命令时自动启动）
npx -y mcp-excalidraw-server start
open http://127.0.0.1:3000 # 可选 – 截图/Mermaid 需要
# 添加两个框和一个箭头（通过标准输入传递 JSON）
echo '[
{"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"}
]' | npx -y mcp-excalidraw-server add
# 让代理查看图表
npx -y mcp-excalidraw-server describe
npx -y mcp-excalidraw-server screenshot --out diagram.png
# 为版本控制导出
npx -y mcp-excalidraw-server export --out docs/architecture.excalidraw
相同的命令也可以从兼容 MCP 的客户端或通过 HTTP 调用。
已知限制 / 未解决问题（摘自 README）
- 服务器默认仅绑定到
127.0.0.1。要对外暴露，用户需要自行配置防火墙或反向代理 – 没有内置身份验证。 - 某些操作（例如
screenshot、mermaid转换）依赖客户端的 Excalidraw UI，因此需要打开浏览器标签页。 - README 中有几个“已知问题 / TODO”部分，但没有列出具体错误；请查看问题跟踪器以获取最新状态。
维护者
该仓库由 yctimlin 所有，并以 mcp-excalidraw-server 发布在 npm 上（MIT 许可证）。持续集成会在每次推送时运行测试并构建 Docker 镜像。
TL;DR
mcp-excalidraw-server 为 AI 编码代理提供了一个真正可编辑的绘图表面，可以通过编程方式控制。它通过简单的 CLI、MCP stdio 服务器或 REST API 工作，并将图表存储为版本控制的 .excalidraw 文件 – 在 LLM 生成的架构想法和具体、可编辑的图表之间架起了一座实用的桥梁。
相关
- 项目
- 项目
- 项目
- 项目
- 项目