excalidraw

excalidraw-mcp-server

唯一一款具备安全加固、内嵌图表渲染和实时画布同步功能的 Excalidraw MCP 服务。

功能介绍

让 AI 绘制图表，图表就会直接出现在聊天窗口中。此 MCP 服务为 Claude Desktop、ChatGPT、VS Code 和 Cursor 提供一整套基于 Excalidraw 格式的绘图工具，并对每项操作进行 API 身份验证、速率限制和输入验证。

v2.0 新增 MCP Apps 支持：图表以交互式 SVG 小组件的形式内嵌流式呈现，并带有绘制动画；你还可以一键将任意图表导出到 excalidraw.com。

两种模式，零配置

独立模式（默认）——安装后即可使用。服务通过进程内元素存储运行。无需画布服务、API 密钥或其他设置。MCP 客户端调用工具，图表便会内嵌渲染。

连接模式——启动可选的画布服务，实现浏览器实时同步。多个客户端可通过经过身份验证的 WebSocket 连接在同一画布上协作。文件持久化可在重启后保留状态。

服务会自动检测要使用的模式：如果能连接到画布服务，就会连接；否则会回退到独立模式。

架构

此图使用 excalidraw-mcp-server 创建——在 Excalidraw 中编辑

功能特性

MCP Apps（v2.0）

• 在 Claude Desktop、ChatGPT 和 VS Code 中内嵌渲染图表
• 随元素到达而流式生成 SVG，并播放绘制动画
• 一键导出到 excalidraw.com
• 通过 read_me 工具查看元素参考速查表

16 个 MCP 工具

• 创建、更新、删除和查询元素（矩形、椭圆、菱形、箭头、文本、直线、自由绘制）
• 一次最多批量创建 100 个元素
• 分组、取消分组、对齐、分布、锁定、解锁
• Mermaid 图表转换
• SVG 和 PNG 导出

安全性

• 使用恒定时间比较进行 API 密钥身份验证
• 限制来源的 CORS（不使用通配符）
• 通过令牌和来源验证进行 WebSocket 身份验证
• 标准和严格的速率限制级别
• 有界 Zod 模式，每个端点均使用 .strict()
• 使用 CSP 的 Helmet.js 安全标头

基础设施

• 在浏览器客户端之间实时进行 WebSocket 同步
• 可选的原子写入文件持久化
• 结构化 pino 审计日志

安装

npm install -g excalidraw-mcp-server

也可以直接运行：

npx excalidraw-mcp-server

快速开始

独立模式（大多数用户推荐）

只需将 MCP 客户端指向此服务。无需画布服务。

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["excalidraw-mcp-server"]
    }
  }
}

然后向 AI 提出请求：“绘制一张架构图，包含一个负载均衡器、三台应用服务器和一个数据库”

连接模式（浏览器实时同步）

# Generate an API key
node scripts/generate-api-key.cjs

# Start the canvas server
EXCALIDRAW_API_KEY=<your-key> npm run canvas

# Open http://localhost:3000 to see the live canvas

使用相同的 API 密钥，将 MCP 客户端指向此服务：

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["excalidraw-mcp-server"],
      "env": {
        "EXCALIDRAW_API_KEY": "<your-key>",
        "CANVAS_SERVER_URL": "http://127.0.0.1:3000"
      }
    }
  }
}

MCP 工具

工具	描述
create_view	将元素渲染为带流式动画的内嵌 SVG 小组件（MCP Apps）
read_me	获取元素参考速查表（类型、颜色、尺寸提示）
create_element	创建单个元素（矩形、椭圆、菱形、箭头、文本、直线、自由绘制）
update_element	按 ID 更新现有元素
delete_element	按 ID 删除元素
query_elements	按类型、锁定状态或组 ID 搜索元素
get_resource	获取场景状态、所有元素、主题或库
batch_create_elements	一次调用最多创建 100 个元素
group_elements	将多个元素编组
ungroup_elements	将元素从组中移除
align_elements	对齐元素（左对齐、居中、右对齐、顶部对齐、垂直居中、底部对齐）
distribute_elements	均匀分布元素（水平或垂直）
lock_elements	锁定元素以防止修改
unlock_elements	解锁元素
create_from_mermaid	将 Mermaid 图表转换为 Excalidraw 元素
export_scene	将画布导出为 SVG 或 PNG

安全性对比

功能	典型 MCP 服务	excalidraw-mcp-server
身份验证	无	API 密钥（恒定时间比较）
CORS	* 通配符	来源允许列表
WebSocket 身份验证	无	令牌 + 来源验证
速率限制	无	标准和严格级别
输入验证	最低限度	带 .strict() 的有界 Zod
安全标头	无	Helmet.js + CSP
请求大小限制	无	请求体 512KB，WebSocket 1MB
审计日志	无	结构化 pino 日志

配置

所有设置均通过环境变量配置。将 .env.example 复制为 .env，并根据需要调整。

变量	默认值	描述
STANDALONE_MODE	true	使用进程内存储（无需画布服务）
CANVAS_HOST	127.0.0.1	画布服务绑定地址
CANVAS_PORT	3000	画布服务端口
EXCALIDRAW_API_KEY	自动生成	用于身份验证的 API 密钥（至少 32 个字符）
CORS_ALLOWED_ORIGINS	http://localhost:3000,http://127.0.0.1:3000	以逗号分隔的来源允许列表
RATE_LIMIT_WINDOW_MS	60000	速率限制时间窗口，单位为毫秒
RATE_LIMIT_MAX_REQUESTS	100	每个时间窗口的最大请求数（标准级别）
PERSISTENCE_ENABLED	false	启用基于文件的持久化
PERSISTENCE_DIR	./data	持久化存储目录
CANVAS_SERVER_URL	http://127.0.0.1:3000	MCP 服务用于连接画布的 URL
LOG_LEVEL	info	日志级别：debug、info、warn、error
AUDIT_LOG_ENABLED	true	启用审计日志
MAX_ELEMENTS	10000	画布上的最大元素数
MAX_BATCH_SIZE	100	批量创建时的最大元素数

MCP 客户端配置

Claude Desktop

添加到 claude_desktop_config.json：

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["excalidraw-mcp-server"]
    }
  }
}

Cursor

添加到项目根目录下的 .cursor/mcp.json：

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["excalidraw-mcp-server"]
    }
  }
}

VS Code

添加到 MCP 设置中：

{
  "mcpServers": {
    "excalidraw": {
      "command": "npx",
      "args": ["excalidraw-mcp-server"]
    }
  }
}

对于连接模式，将 "env": { "EXCALIDRAW_API_KEY": "<key>", "CANVAS_SERVER_URL": "http://127.0.0.1:3000" } 添加到上述配置中。将 <key> 替换为通过 node scripts/generate-api-key.cjs 生成的密钥。

开发

# Install dependencies
npm ci

# Run in development mode (watch + Vite dev server)
npm run dev

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Lint
npm run lint

# Type check
npm run type-check

# Build (server + widget + frontend)
npm run build

项目结构

src/
  mcp/              MCP server (stdio transport)
    tools/          16 tool implementations
    apps/           MCP Apps wiring, standalone store, cheatsheet
    schemas/        Zod schemas and input limits
    canvas-client.ts  HTTP client for canvas server
    index.ts        MCP server entry point
  canvas/           Canvas server (Express + WebSocket)
    middleware/      Auth, CORS, rate limiting, audit, security headers
    routes/         REST API routes + SVG export
    ws/             WebSocket handler and protocol
    store/          Element storage (memory + file)
    index.ts        Canvas server entry point
  shared/           Shared config, types, logging
widget/             MCP Apps inline widget (Vite + singlefile build)
frontend/           Excalidraw React frontend (browser)
test/               Unit and integration tests (290 tests)

从 v1.x 迁移

零配置升级。原有的全部 14 个工具均可照常使用，新增了 create_view 和 read_me。画布服务现在是可选的（会自动启用独立模式）。

npm install -g excalidraw-mcp-server@2

现有 MCP 客户端配置（stdio 传输、工具名称）无需更改即可继续使用。

许可证

MIT