Excalidraw MCP 服务器：强大的绘图 API 用于 LLM 集成

这是一个全面的模型上下文协议（MCP）服务器，它能够与 Excalidraw 图表和绘图进行无缝交互。此服务器通过结构化且对开发者友好的 API 向大型语言模型 (LLMs) 提供创建、修改、查询和操作 Excalidraw 绘图的能力。

特性

• 完整的 Excalidraw 元素控制
  创建、更新、删除和查询任何 Excalidraw 元素（矩形、椭圆、菱形、文本、箭头等），包括支持：
  • 位置 (x, y)
  • 尺寸 (width, height)
  • 样式 (backgroundColor, strokeColor, strokeWidth, roughness, opacity)
  • 文本 (text, fontSize, fontFamily)
  • 线条几何 (points)
  • 锁定 (locked 标志)
• 高级元素操作
  分组、解组、对齐、分布、锁定和解锁元素。
• 场景 & 应用状态管理
  • 跟踪并修改场景级状态：theme, viewBackgroundColor, viewport (滚动 & 缩放), selectedElements, groups。
  • 检索所有元素库或个别场景属性。
• 保存场景
  将当前场景（元素 + 应用状态）导出到磁盘上的 .excalidraw 文件中。
• 资源管理
  访问和修改场景信息、元素库、主题以及原始元素数据。
• 轻松集成
  与 Claude Desktop、Cursor 以及其他支持 MCP 的 LLM 平台兼容。
• Docker 支持
  简单的容器化部署，实现零依赖安装。

---

API 工具参考

元素创建和修改

create_element

创建一个新的 Excalidraw 元素。

• 输入

  {
    "type": "<element type>",
    "x": <number>,
    "y": <number>,
    "width": <number, optional>,
    "height": <number, optional>,
    "points": [{"x":<number>,"y":<number>}…],
    "backgroundColor": "<hex>",
    "strokeColor": "<hex>",
    "strokeWidth": <number>,
    "roughness": <number>,
    "opacity": <0–1>,
    "text": "<string>",
    "fontSize": <number>,
    "fontFamily": "<string>",
    "locked": <boolean>
  }
  

• 输出

  { "id": "<generated‑id>", "type": "<element type>", "created": true }
  

update_element

更新现有元素的属性。

• 输入

  {
    "id": "<element id>",
  }
  

• 输出

  { "id": "<element id>", "updated": true, "version": <new‑version‑number> }
  

delete_element

从场景中移除一个元素。

• 输入

  { "id": "<element id>" }
  

• 输出

  { "id": "<element id>", "deleted": true }
  

query_elements

列出符合可选过滤条件的元素。

• 输入

  {
    "type": "<element type>",        
    "filter": { "<prop>": <value> }  
  }
  

• 输出

  [ { /* element objects */ } … ]
  

资源管理

get_resource

获取指定的资源信息。

检索场景或库信息。

• 输入

  { "resource": "scene"|"library"|"theme"|"elements" }
  

• 输出
  • scene → { theme, viewport: {x,y,zoom}, selectedElements: […] }
  • library/elements → { elements: [ … ] }
  • theme → { theme: "light"|"dark" }

元素组织

group_elements / ungroup_elements

对元素集合进行分组或取消分组。

• 输入

  { "elementIds": ["id1","id2",…] }
  { "groupId": "<group id>" }
  

• 输出

  { "groupId": "<new‑id>", "elementIds": […], "ungrouped": true? }
  

align_elements

将多个元素对齐到指定的边缘或中心。

• 输入

  { "elementIds": […], "alignment": "left"|"center"|"right"|"top"|"middle"|"bottom" }
  

• 输出
  { aligned: true, elementIds: […], alignment: "<alignment>" }

distribute_elements

水平或垂直均匀分布元素。

• 输入

  { "elementIds": […], "direction": "horizontal"|"vertical" }
  

• 输出
  { distributed: true, elementIds: […], direction: "<direction>" }

lock_elements / unlock_elements

阻止或允许编辑元素。

• 输入

  { "elementIds": [… ] }
  

• 输出
  { locked: true|false, elementIds: […] }

场景管理

save_scene

将当前场景（元素 + 应用状态）导出为 .excalidraw 文件。

• 输入

  { "filename": "<optional, must end with .excalidraw>" }
  

• 输出
  Scene saved successfully to <filename> 或错误消息。

---

集成示例

Claude Desktop

"mcpServers": {
  "excalidraw": {
    "command": "node",
    "args": ["src/index.js"],
    "env": {
      "LOG_LEVEL": "info",
      "DEBUG": "false"
    }
  }
}

Cursor

创建 .cursor/mcp.json：

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"],
      "env": { "LOG_LEVEL": "info", "DEBUG": "false" }
    }
  }
}

Docker

docker run -i --rm mcp/excalidraw

或者在 MCP 配置中：

"mcpServers": {
  "excalidraw": {
    "command": "docker",
    "args": ["run", "-i", "--rm", "mcp/excalidraw"],
    "env": { "LOG_LEVEL": "info", "DEBUG": "false" }
  }
}

---

安装指南

# Install dependencies
npm install

# Run development server
npm start

Docker

docker build -t mcp/excalidraw .
docker run -i --rm mcp/excalidraw

---

配置选项

通过环境变量在 .env 或容器中设置：

• LOG_LEVEL — 日志级别（默认："info"）
• DEBUG — 调试模式（"true"/"false"，默认："false"）
• DEFAULT_THEME — 默认 UI 主题（"light"/"dark"，默认："light"）

---

使用示例

创建并锁定一个矩形

{"type":"rectangle","x":50,"y":50,"width":100,"height":80,"backgroundColor":"#f3f3f3","strokeColor":"#333","locked":true}

{ "id":"abc123","type":"rectangle","created":true }

{"elementIds":["abc123"]}

将场景保存到文件

{"filename":"my_drawing.excalidraw"}

"Scene saved successfully to my_drawing.excalidraw"