MCP excalidraw

排除MCP服务器和代理技能

运行一个实时Excalidraw画布，并从AI代理控制它。此回购提供：

• MCP服务器：通过模型上下文协议连接（Claude Desktop、Cursor、Codex CLI等）
• 代理技能：Claude Code、Codex CLI和其他技能型代理的可移植技能

关键词：Excalidraw代理技能，ExcalidrawMCP服务器，AI绘图，Claude代码技能，Codex CLI技能，Claude桌面MCP，光标MCP，美人鱼到Exalidraw。

演示

*AI代理从单个提示（4倍速度）创建完整的架构图。 在YouTube上观看完整视频*

目录

• 演示
• 它是什么
• 我们与官方Excalidraw MCP有何不同
• 新增功能
• 快速入门（本地）
• 配置MCP客户端

- 克劳德桌面 - 克劳德代码 - 光标 - Codex CLI - 开源代码 - 反重力（谷歌）

• 代理技能（可选）
• MCP工具（共26个）
• 测试
• 故障排除
• 已知问题/待办事项
• 发展

它是什么

此仓库包含两个单独的流程：

• Canvas服务器：web UI+REST API+WebSocket更新（默认 http://127.0.0.1:3000)
• MCP服务器：通过stdio公开MCP工具；通过以下方式同步到画布 EXPRESS_SERVER_URL

我们与官方Excalidraw MCP有何不同

Excalidraw现在有一个 官方MCP --它非常适合在聊天中快速、快速地生成内联渲染的图表。我们解决了一个不同的问题。

太长，读不下去了 --官方MCP生成图表。我们为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生成的图表质量
• 可共享URL: export_to_excalidraw_url 将场景加密并上传到excalidraw.com，返回任何人都可以打开的可共享链接
• 视口控制: set_viewport 和 scrollToContent, scrollToElementId，或手动缩放/偏移--代理可以在创建后自动调整图表
• 文件I/O：出口/进口已满 .excalidraw JSON文件
• 快照：保存和恢复命名画布状态
• 技能回退：代理技能自动检测MCP与REST API模式，在未配置MCP服务器时，正常地回退到HTTP端点
• 修复了所有以前已知的问题： align_elements / distribute_elements 完全实现，点类型规范化，删除无效 label 类型，删除HTTP传输死代码， ungroup_elements 现在失败时出错

v1.x

• 代理技能： skills/excalidraw-skill/ （可移植指令+用于导出/导入和可重复CRUD的辅助脚本）
• 更好的测试循环：MCP Inspector CLI示例+浏览器屏幕截图检查(agent-browser)
• Bug修复：批量创建现在保留元素id（修复批量后的更新/删除）；前端入口点已固定(main.tsx)

快速入门（本地）

前提条件：节点>=18，npm

npm ci
npm run build

终端1：启动画布

PORT=3000 npm run canvas

安全说明： 服务器默认绑定到 127.0.0.1 只有。如果需要在网络接口（例如Docker、远程访问）上公开它，请设置 HOST=0.0.0.0 -但请确保您有适当的网络级访问控制，因为API没有内置身份验证。

打开 http://127.0.0.1:3000.

终端2：运行MCP服务器（stdio）

EXPRESS_SERVER_URL=http://127.0.0.1:3000 node dist/index.js

快速入门（Docker）

画布服务器：

docker run -d -p 3000:3000 --name mcp-excalidraw-canvas ghcr.io/yctimlin/mcp_excalidraw-canvas:latest

MCP服务器（stdio）通常由您的MCP客户端（Claude Desktop/Cursor等）启动。如果你想要一个本地容器，请使用图像 ghcr.io/yctimlin/mcp_excalidraw:latest 并设置 EXPRESS_SERVER_URL 指向画布。

配置MCP客户端

MCP服务器通过stdio运行，可以配置任何兼容MCP的客户端。以下是两者的配置 本地 （需要克隆和构建）以及 码头工人 （拉动并运行）设置。

环境变量

______________________________________________________________________

克劳德桌面

配置位置：

• macOS： ~/Library/Application Support/Claude/claude_desktop_config.json
• 窗户： %APPDATA%\Claude\claude_desktop_config.json
• Linux： ~/.config/Claude/claude_desktop_config.json

本地（节点）

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

码头工人

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

______________________________________________________________________

克劳德代码

使用 claude mcp add 注册MCP服务器的命令。

本地（节点） -用户级别（适用于所有项目）：

claude mcp add excalidraw --scope user \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

本地（节点） -项目级别（通过共享 .mcp.json):

claude mcp add excalidraw --scope project \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

码头工人

claude mcp add excalidraw --scope user \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

管理服务器：

claude mcp list              # List configured servers
claude mcp remove excalidraw # Remove a server

______________________________________________________________________

光标

配置位置： .cursor/mcp.json 在项目根目录中（或 ~/.cursor/mcp.json 全局配置）

本地（节点）

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

码头工人

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

______________________________________________________________________

Codex CLI

使用 codex mcp add 注册MCP服务器的命令。

本地（节点）

codex mcp add excalidraw \
  --env EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  --env ENABLE_CANVAS_SYNC=true \
  -- node /absolute/path/to/mcp_excalidraw/dist/index.js

码头工人

codex mcp add excalidraw \
  -- docker run -i --rm \
  -e EXPRESS_SERVER_URL=http://host.docker.internal:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  ghcr.io/yctimlin/mcp_excalidraw:latest

管理服务器：

codex mcp list              # List configured servers
codex mcp remove excalidraw # Remove a server

______________________________________________________________________

开源代码

配置位置： ~/.config/opencode/opencode.json 或项目级别 opencode.json

本地（节点）

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["node", "/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "enabled": true,
      "environment": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

码头工人

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "excalidraw": {
      "type": "local",
      "command": ["docker", "run", "-i", "--rm", "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000", "-e", "ENABLE_CANVAS_SYNC=true", "ghcr.io/yctimlin/mcp_excalidraw:latest"],
      "enabled": true
    }
  }
}

______________________________________________________________________

反重力（谷歌）

配置位置： ~/.gemini/antigravity/mcp_config.json

本地（节点）

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://127.0.0.1:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

码头工人

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "EXPRESS_SERVER_URL=http://host.docker.internal:3000",
        "-e", "ENABLE_CANVAS_SYNC=true",
        "ghcr.io/yctimlin/mcp_excalidraw:latest"
      ]
    }
  }
}

______________________________________________________________________

备注

• Docker网络：使用 host.docker.internal 访问主机上运行的canvas服务器。在Linux上，您可能需要 --add-host=host.docker.internal:host-gateway 或使用 172.17.0.1.
• Canvas服务器：必须在MCP服务器连接之前运行。从以下内容开始 npm run canvas （本地）或 docker run -d -p 3000:3000 ghcr.io/yctimlin/mcp_excalidraw-canvas:latest （Docker）。
• 绝对路径：使用本地节点设置时，请替换 /absolute/path/to/mcp_excalidraw 使用克隆和构建仓库的实际路径。
• 内存存储：canvas服务器将元素存储在内存中。重新启动服务器将清除所有元素。如果需要持久性，请使用导出/导入脚本。

代理技能（可选）

此repo包括以下技能 skills/excalidraw-skill/ 它提供：

• 工作流程手册 (SKILL.md)：绘制、细化和导出图表的分步指南
• 小抄 (references/cheatsheet.md)：MCP工具和REST API参考
• 辅助脚本 (scripts/*.cjs)：导出、导入、清除、健康检查、CRUD操作

该技能通过为您的AI代理提供结构化的工作流程来补充MCP服务器。

安装技能（Codex CLI示例）

mkdir -p ~/.codex/skills
cp -R skills/excalidraw-skill ~/.codex/skills/excalidraw-skill

要更新现有安装，请先删除旧文件夹(rm -rf ~/.codex/skills/excalidraw-skill)然后重新复制。

安装技能（克劳德代码）

用户级别 （适用于您的所有项目）：

mkdir -p ~/.claude/skills
cp -R skills/excalidraw-skill ~/.claude/skills/excalidraw-skill

项目级别 （适用于特定项目，可以提交到仓库）：

mkdir -p /path/to/your/project/.claude/skills
cp -R skills/excalidraw-skill /path/to/your/project/.claude/skills/excalidraw-skill

然后调用Claude Code中的技能 /excalidraw-skill.

要更新现有安装，请先删除旧文件夹，然后重新复制。

使用技能脚本

所有脚本均受尊重 EXPRESS_SERVER_URL （默认值 http://127.0.0.1:3000)或接受 --url.

EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/healthcheck.cjs
EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/export-elements.cjs --out diagram.elements.json
EXPRESS_SERVER_URL=http://127.0.0.1:3000 node skills/excalidraw-skill/scripts/import-elements.cjs --in diagram.elements.json --mode batch

当技能有用时

• 存储库工作流程：将元素导出为JSON，提交后重新导入。
• 可靠的重构：清除+重新导入 sync 模式使画布与文件匹配。
• 自动烟雾测试：创建/更新/删除已知元素以验证部署。
• 可重复的图表：保留一个元素JSON片段库并导入它们。

看 skills/excalidraw-skill/SKILL.md 和 skills/excalidraw-skill/references/cheatsheet.md.

MCP工具（共26个）

可以通过以下方式发现完整的架构 tools/list 或在 skills/excalidraw-skill/references/cheatsheet.md.

测试

画布烟雾测试（HTTP）

curl http://127.0.0.1:3000/health

本地绑定回归测试

npm run test:bind

MCP烟雾测试（MCP检查员）

列出工具：

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/list

创建矩形：

npx @modelcontextprotocol/inspector --cli \
  -e EXPRESS_SERVER_URL=http://127.0.0.1:3000 \
  -e ENABLE_CANVAS_SYNC=true -- \
  node dist/index.js --method tools/call --tool-name create_element \
  --tool-arg type=rectangle --tool-arg x=100 --tool-arg y=100 \
  --tool-arg width=300 --tool-arg height=200

前端截图（代理浏览器）

如果你使用 agent-browser 对于UI检查：

agent-browser install
agent-browser open http://127.0.0.1:3000
agent-browser wait --load networkidle
agent-browser screenshot /tmp/canvas.png

故障排除

• 画布未更新：确认 EXPRESS_SERVER_URL 指向正在运行的canvas服务器。
• 批创建后更新/删除失败：请确保您使用的版本包含批id保留修复程序（通过PR#34合并）。

已知问题/待办事项

之前列出的所有错误都已在v2.0中修复。剩余项目：

• \[ \] 持久存储：元素存储在内存中——重新启动服务器会清除所有内容。使用 export_scene /快照作为一种解决方法。
• \[ \] 图像导出需要浏览器: export_to_image 和 get_canvas_screenshot 依赖前端进行实际渲染。画布UI必须在浏览器中打开。

欢迎投稿！

发展

npm run type-check
npm run build