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.

GAI 中文摘要

mcp_excalidraw 是一个基于 JavaScript 开发的 Excalidraw MCP 服务器及 AI 代理技能工具，旨在通过 MCP 协议实现 AI 对画布元素的实时编程控制。该项目通过提供持久化的画布服务，解决了传统 AI 绘图工具无法进行元素级精细编辑和迭代优化的痛点。

它支持通过 AI 代理对画布进行实时增删改查，包含多达 26 种精细化的 MCP 操作工具。系统提供基于 REST API 和 WebSocket 的实时画布同步功能，确保 AI 与可视化界面高度联动。用户可以通过 describe_scene 获取场景结构描述，并利用 get_canvas_screenshot 功能实现 AI 对画布内容的视觉感知。该工具能够将自然语言指令转化为复杂的架构图或流程图，并支持在原有画布基础上进行迭代修改。

该项目非常适合需要使用 Claude Desktop、Cursor 或 Claude Code 等 AI 工具进行复杂系统架构设计与流程建模的开发者。它特别适用于需要通过 AI 频繁调整、持续优化视觉图表的专业绘图场景。

⭐

2.0k

Stars

🔱

213

Forks

👁

Watchers

📋

Issues

JavaScriptMIT创建于 2025/3/16更新于今天

在 GitHub 上查看

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。

演示

MCP Excalidraw Demo

AI Agent 仅通过一个提示词即创建出完整的架构图（4倍速）。在 YouTube 上观看完整视频

项目简介

本项目包含两个独立进程：

Canvas server：Web UI + REST API + WebSocket 更新（默认地址 http://127.0.0.1:3000）。
MCP server：通过 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	聊天内嵌渲染	独立 Excalidraw 应用，通过 WebSocket 同步
多 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：支持导出/导入。