t

testzzcz

apach3/testzzcz
0 Stars 4 次浏览 更新于 2026-08-23

一个综合系统，结合了Excalidraw强大的绘图功能与模型上下文协议（MCP）的集成，使AI代理能够在实时在线环境中创建和操作图表。

开发者工具

MCP 服务配置

复制以下 JSON 到 OPClaw 或其他 MCP 客户端的配置文件中即可使用

{
  "mcpServers": {
    "excalidraw": {
      "args": [
        "run",
        "-i",
        "--rm",
        "mcp-excalidraw-server"
      ],
      "command": "docker"
    }
  }
}

服务介绍

MCP Excalidraw 服务器：结合AI的高级实时可视化绘图

一个综合系统，将 Excalidraw 强大的绘图功能 与 模型上下文协议 (MCP) 集成在一起，使 AI 代理能够在实时画布上创建和操作图表。

🚦 当前状态及版本信息

📋 选择您的安装方法

版本 状态 推荐用途
本地开发 ✅ 完全测试 🎯 推荐
NPM 发布版 🔧 调试中 开发测试
Docker 版本 🔧 开发中 未来的部署

当前推荐：本地开发

为了获得最稳定的体验，我们建议使用本地开发设置。我们正在积极改进 NPM 包和 Docker 部署选项。

开发说明

  • NPM 包: 目前正在调试 MCP 工具注册问题
  • Docker 版本: 正在提高画布同步的可靠性
  • 本地版本: ✅ 所有功能完全可用

🚀 该系统的作用

  • 🎨 实时画布: 可通过网页浏览器访问的实时 Excalidraw 画布
  • 🤖 AI 集成: MCP 服务器允许 AI 代理（如 Claude）创建视觉图表
  • ⚡ 实时同步: 通过 MCP API 创建的元素会立即出现在画布上
  • 🔄 WebSocket 更新: 多个连接客户端之间的实时同步
  • 🏗️ 生产就绪: 清晰、简洁的用户界面适合最终用户

🎥 演示视频

观看 MCP Excalidraw 的实际效果！

MCP Excalidraw 演示

观看 AI 代理如何在实时画布上创建和操作图表

🏛️ 架构概览


┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐

│   AI Agent      │───▶│   MCP Server     │───▶│  Canvas Server  │

│   (Claude)      │    │  (src/index.js) │    │ (src/server.js) │

└─────────────────┘    └──────────────────┘    └─────────────────┘

                                                         │

                                                         ▼

                                               ┌─────────────────┐

                                               │  Frontend       │

                                               │  (React + WS)   │

                                               └─────────────────┘

🌟 主要特性

实时画布集成

  • 通过 MCP 创建的元素会立即出现在实时画布上
  • 基于 WebSocket 的实时同步
  • 支持多客户端并提供实时更新

生产就绪的界面

  • 清晰、简洁的用户界面，显示连接状态
  • 简单的“清除画布”功能
  • 无开发杂乱或调试信息

全面的 MCP API

  • 元素创建: 矩形、椭圆、菱形、箭头、文本、线条
  • 元素管理: 更新、删除、带过滤条件的查询
  • 批量操作: 一次调用创建多个元素
  • 高级功能: 分组、对齐、分布、锁定

健壮的架构

  • Express.js 后端，支持 REST API 和 WebSocket
  • React 前端，使用官方 Excalidraw 包
  • 双路径元素加载以提高可靠性
  • 自动重连和错误处理

📦 安装与设置

✅ 推荐：本地开发设置

最稳定且功能完整的选项

1. 克隆仓库

git clone https://github.com/yctimlin/mcp_excalidraw.git
cd mcp_excalidraw
npm install

2. 构建前端

npm run build

3. 启动系统

选项 A: 生产模式（推荐）
# Start canvas server (serves frontend + API)
npm run canvas
选项 B: 开发模式
# Start both canvas server and Vite dev server
npm run dev

4. 访问画布

打开您的浏览器并导航至：

http://localhost:3000

🔧 替代安装方法（开发中）

NPM 包（测试版）

# Currently debugging tool registration - feedback welcome!
npm install -g mcp-excalidraw-server
npx mcp-excalidraw-server

Docker 版本（即将推出）

# Canvas sync improvements in progress
docker run -p 3000:3000 mcp-excalidraw-server

🔧 可用脚本

脚本 描述
npm start 启动 MCP 服务器 (src/index.js)
npm run canvas 启动画布服务器 (src/server.js)
npm run build 构建用于生产的前端
npm run dev 启动画布 + Vite 开发服务器
npm run production 构建并以生产模式启动

🎯 使用指南

对于最终用户

  1. 在 http://localhost:3000 打开画布
  2. 检查连接状态（应显示“已连接”）
  3. AI 代理现在可以创建实时出现的图表
  4. 使用“清除画布”来移除所有元素

**对于 AI 代理（通过 MCP）**MCP 服务器提供了这些工具来创建可视化图表：

基本元素创建

// Create a rectangle
{
  "type": "rectangle",
  "x": 100,
  "y": 100, 
  "width": 200,
  "height": 100,
  "backgroundColor": "#e3f2fd",
  "strokeColor": "#1976d2",
  "strokeWidth": 2
}

创建文本元素

{
  "type": "text",
  "x": 150,
  "y": 125,
  "text": "Process Step",
  "fontSize": 16,
  "strokeColor": "#333333"
}

创建箭头和线条

{
  "type": "arrow",
  "x": 300,
  "y": 130,
  "width": 100,
  "height": 0,
  "strokeColor": "#666666",
  "strokeWidth": 2
}

复杂图表的批量创建

{
  "elements": [
    {
      "type": "rectangle",
      "x": 100,
      "y": 100,
      "width": 120,
      "height": 60,
      "backgroundColor": "#fff3e0",
      "strokeColor": "#ff9800"
    },
    {
      "type": "text", 
      "x": 130,
      "y": 125,
      "text": "Start",
      "fontSize": 16
    }
  ]
}

🔌 与 Claude Desktop 集成

✅ 推荐：使用本地安装

对于本地开发版本（最稳定），请在您的 claude_desktop_config.json 中添加以下配置：


{

  "mcpServers": {

    "excalidraw": {

      "command": "node",

      "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"]

    }

  }

}

重要提示：将 /absolute/path/to/mcp_excalidraw 替换为您克隆仓库的实际绝对路径。

🔧 备选配置（测试版）

NPM 包（测试中）

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

当前正在调试工具注册 - 如果您遇到问题，请告知我们！

Docker 版本（即将推出）

{
  "mcpServers": {
    "excalidraw": {
      "command": "docker",
      "args": ["run", "-i", "--rm", "mcp-excalidraw-server"]
    }
  }
}

画布同步改进正在进行中。

🔧 与其他工具集成

Cursor IDE

在您的 .cursor/mcp.json 中添加：


{

  "mcpServers": {

    "excalidraw": {

      "command": "node",

      "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"]

    }

  }

}

VS Code MCP 扩展

对于 VS Code MCP 扩展，在设置中添加：


{

  "mcp": {

    "servers": {

      "excalidraw": {

        "command": "node",

        "args": ["/absolute/path/to/mcp_excalidraw/src/index.js"]

      }

    }

  }

}

🛠️ 环境变量

变量 默认值 描述
EXPRESS_SERVER_URL http://localhost:3000 用于 MCP 同步的画布服务器 URL
ENABLE_CANVAS_SYNC true 启用/禁用画布同步
DEBUG false 启用调试日志
PORT 3000 画布服务器端口
HOST localhost 画布服务器主机

📊 API 端点

画布服务器提供以下 REST 端点：

方法 端点 描述
GET /api/elements 获取所有元素
POST /api/elements 创建新元素
PUT /api/elements/:id 更新元素
DELETE /api/elements/:id 删除元素
POST /api/elements/batch 创建多个元素
GET /health 服务器健康检查

🎨 可用的 MCP 工具

元素管理

  • create_element - 创建任何类型的 Excalidraw 元素
  • update_element - 修改现有元素
  • delete_element - 删除元素
  • query_elements - 使用过滤器搜索元素

批量操作

  • batch_create_elements - 一次调用创建复杂的图表

元素组织

  • group_elements - 组合多个元素
  • ungroup_elements - 解组元素组
  • align_elements - 对齐元素（左、中、右、上、中、下）
  • distribute_elements - 均匀分布元素
  • lock_elements / unlock_elements - 锁定/解锁元素

资源访问

  • get_resource - 访问场景、库、主题或元素数据

🏗️ 开发架构

前端 (frontend/src/)

  • React + Vite：现代构建系统
  • 官方 Excalidraw：@excalidraw/excalidraw 包
  • WebSocket 客户端：实时元素同步
  • 简洁 UI：生产就绪界面

画布服务器 (src/server.js)

  • Express.js：REST API 和静态文件服务
  • WebSocket：实时客户端通信
  • 元素存储：内存中存储，支持持久化选项
  • CORS：跨域支持

MCP 服务器 (src/index.js)

  • MCP 协议：标准模型上下文协议
  • 画布同步：向画布服务器发送 HTTP 请求
  • 元素管理：完整的 CRUD 操作
  • 批量支持：复杂图表创建

🐛 故障排除

NPM 包问题

  • 症状：MCP 工具未正确注册
  • 临时解决方案：使用本地开发设置
  • 状态：正在积极调试 - 即将更新

Docker 版本注意事项

  • 症状：元素可能不会立即同步到画布
  • 临时解决方案：使用本地开发设置
  • 状态：正在改进同步可靠性

画布无法加载

  • 确保 npm run build 成功完成
  • 检查 dist/index.html 是否存在- 确认 canvas 服务器在 3000 端口上运行

元素不同步

  • 确认 MCP 服务器正在运行 (npm start)
  • 检查环境变量中 ENABLE_CANVAS_SYNC=true
  • 确认可以通过 EXPRESS_SERVER_URL 访问 canvas 服务器

WebSocket 连接问题

  • 检查浏览器控制台中的 WebSocket 错误
  • 确保没有防火墙阻止 WebSocket 连接
  • 尝试刷新浏览器页面

构建错误

  • 删除 node_modules 并运行 npm install
  • 检查 Node.js 版本（需要 16+）
  • 确保所有依赖项都已安装

📋 项目结构


mcp_excalidraw/

├── frontend/

│   ├── src/

│   │   ├── App.jsx          # Main React component

│   │   └── main.jsx         # React entry point

│   └── index.html           # HTML template

├── src/

│   ├── index.js            # MCP server

│   ├── server.js           # Canvas server (Express + WebSocket)

│   ├── types.js            # Shared types and utilities

│   └── utils/

│       └── logger.js       # Logging utility

├── dist/                   # Built frontend (generated)

├── vite.config.js         # Vite build configuration

├── package.json           # Dependencies and scripts

└── README.md              # This file

🔮 开发路线图

  • NPM 包: 解决 MCP 工具注册问题
  • Docker 部署: 改进 canvas 同步
  • 增强功能: 添加更多 MCP 工具和功能
  • 性能优化: 实时同步改进

🤝 贡献

我们欢迎贡献！如果您在使用 NPM 包或 Docker 版本时遇到问题，请：

  1. 叉取仓库
  2. 创建一个特性分支 (git checkout -b feature/amazing-feature)
  3. 提交您的更改 (git commit -m 'Add amazing feature')
  4. 推送到该分支 (git push origin feature/amazing-feature)
  5. 打开一个 Pull Request

📝 许可证

此项目根据 MIT 许可证发布 - 详情请参阅 LICENSE 文件。

🙏 致谢

  • Excalidraw 团队 - 提供了出色的绘图库
  • MCP 社区 - 提供了 Model Context Protocol 规范
查看源码 项目主页

相关 MCP 服务

LeetCode(力扣)
jinzcdev/leetcode-mcp-server
MCP 服务器实现 LeetCode API 集成，支持自动化获取编程题库、用户数据和竞赛信息。
可视化图表-MCP-Server
antvis/mcp-server-chart
这是一个基于AntV的模型上下文协议服务器，用于生成图表。它支持超过20种类型的图表，并且可以与多种桌面应用程序和平台一起使用。
微软Playwright
@microsoft/playwright-mcp
一种模型上下文协议服务器，它使大型语言模型能够通过结构化的可访问性快照与网页交互，而无需使用视觉模型或截图。
MCP上下文模型文档
@upstash/context7-mcp
一种模型上下文协议服务器，它从库中直接获取最新、特定版本的文档和代码示例并将其引入LLM提示中，帮助开发人员在无需过时或虚构信息的情况下获得准确的答案。