麦普绘图板

Name: 麦普绘图板
Author: yctimlin

作者：yctimlin449 星标更新：2025-11-08

安装使用来源：spider==github.com

项目介绍

技术文档摘要

MCP Excalidraw 服务器：集成AI的实时可视化绘图

一个基于TypeScript的综合系统，结合了Excalidraw的强大绘图能力与**模型上下文协议（MCP）**集成，使AI代理能够在实时画布上创建和操作图表。

🚦 当前状态及版本信息

📋 选择您的安装方法

组件	本地	Docker	状态
画布服务器	✅ 完全工作	✅ 完全工作	生产就绪
MCP服务器	✅ 完全工作	✅ 完全工作	生产就绪
NPM发布	🔧 进行中	N/A	开发测试

重要提示：画布和MCP服务器独立运行

该系统由两个独立组件组成：

画布服务器 - 运行实时Excalidraw画布（Web界面）
MCP服务器 - 连接到Claude Desktop/Claude Code/Cursor IDE

您可以选择任意组合：

画布：本地或Docker
MCP服务器：本地或Docker

本地和Docker设置均完全工作且生产就绪！

🚀 该系统能做什么

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

🎥 演示视频

观看MCP Excalidraw的实际操作！

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

🏛️ 架构概述

两个独立组件

┌─────────────────────────────────────────────────────────────────┐
│                         组件1                                    │
│                     🎨 画布服务器                                │
│                   （独立运行）                                  │
│                                                                  │
│  ┌─────────────────┐         ┌─────────────────┐               │
│  │  画布服务器     │◀───────▶│   前端         │               │
│  │ (src/server.js) │         │  (React + WS)   │               │
│  │  端口3000      │         │  Excalidraw UI  │               │
│  └─────────────────┘         └─────────────────┘               │
│                                                                  │
│  📍 启动：npm run canvas 或 docker run (canvas)                 │
└─────────────────────────────────────────────────────────────────┘

                              ▲
                              │ HTTP API
                              │ (可选)
                              │
┌─────────────────────────────────────────────────────────────────┐
│                         组件2                                    │
│                      🤖 MCP服务器                                │
│                   （独立运行）                                  │
│                                                                  │
│  ┌─────────────────┐         ┌─────────────────┐               │
│  │   AI代理       │◀───────▶│   MCP服务器     │               │
│  │   (Claude)     │         │ (src/index.js)  │               │
│  │  桌面/代码     │  stdio  │  MCP协议       │               │
│  └─────────────────┘         └─────────────────┘               │
│                                                                  │
│  📍 配置于：claude_desktop_config.json 或 .mcp.json             │
└─────────────────────────────────────────────────────────────────┘

🎯 关键点：
• 画布和MCP服务器是分开的进程
• 画布可以本地运行或使用Docker
• MCP服务器可以本地运行或使用Docker
• 画布提供可视界面（可选）
• MCP服务器通过HTTP API连接Claude到画布

🌟 主要功能

现代TypeScript架构

完整的TypeScript迁移：后端和前端的完全类型安全
全面的类型定义：Excalidraw元素、API响应、WebSocket消息
严格的类型检查：增强开发体验和编译时错误检测
类型安全的React组件：具有适当属性类型的TSX组件

🎨 Mermaid图表支持（新！）

Mermaid转Excalidraw：直接将Mermaid图表转换为Excalidraw元素
MCP工具集成：使用Claude的create_from_mermaid工具
基于浏览器的转换：利用前端DOM访问进行准确渲染
多种图表类型：支持流程图、序列图、类图等
测试按钮：从画布UI快速测试功能

实时画布集成

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

生产就绪界面

清洁、简洁的用户界面，带有连接状态
简单的“清除画布”功能
没有开发杂乱或调试信息

全面的MCP API

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

强大的架构

基于TypeScript的Express.js后端，带有REST API + WebSocket
使用官方Excalidraw包和TypeScript的React前端
双路径元素加载以确保可靠性
自动重连和错误处理

📦 安装与设置

步骤1：选择您的画布服务器设置

画布服务器提供实时Excalidraw界面。

选项A：本地画布服务器

克隆并安装

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

构建项目

npm run build

启动画布服务器

# 生产模式（推荐）
npm run canvas

访问画布

http://localhost:3000

选项B：Docker画布服务器

选项B1：使用GHCR上的预构建镜像（推荐）

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

选项B2：本地构建

git clone https://github.com/yctimlin/mcp_excalidraw.git
cd mcp_excalidraw
docker build -f Dockerfile.canvas -t mcp-excalidraw-canvas .
docker run -d -p  3000:3000 --name mcp-excalidraw-canvas mcp-excalidraw-canvas

访问画布

http://localhost:3000

步骤2：在IDE中配置MCP服务器

MCP服务器将您的AI助手（Claude）连接到画布。根据您的偏好选择本地或Docker格式。

设置组合

您可以混合搭配任何组合：

画布服务器	MCP服务器	状态
✅ 本地	✅ 本地	推荐
✅ 本地	✅ Docker	完全工作
✅ Docker	✅ 本地	完全工作
✅ Docker	✅ Docker	完全工作

配置示例将在下一节中提供：

Claude桌面
Claude代码
Cursor IDE

🔧 可用脚本

脚本	描述
`npm start`	构建并启动MCP服务器（`dist/index.js`）
`npm run canvas`	构建并启动画布服务器（`dist/server.js`）
`npm run build`	构建前端和TypeScript后端
`npm run build:frontend`	仅构建React前端
`npm run build:server`	将TypeScript后端编译为JavaScript
`npm run dev`	启动TypeScript监视模式 + Vite开发服务器
`npm run type-check`	运行TypeScript类型检查而不编译
`npm run production`	构建并启动生产模式

🎯 使用指南

对于最终用户

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

对于AI代理（通过MCP）

MCP服务器提供了这些工具来创建视觉图表：

基本元素创建

// 创建矩形
{
  "type": "rectangle",
  "x": 100,
  "y": 100, 
  "width": 200,
  "height": 100,
  "backgroundColor": "#e3f2fd",
  "strokeColor": "#1976d2",
  "strokeWidth": 2
}

创建文本元素

{
  "type": "text",
  "x": 150,
  "y": 125,
  "text": "过程步骤",
  "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": "开始",
      "fontSize": 16
    }
  ]
}

🔌 MCP服务器配置用于IDE

前提条件

✅ 确保您的画布服务器正在运行（来自步骤1）：

本地：npm run canvas
Docker：docker run -d -p 3000:3000 mcp-excalidraw-canvas

画布应在http://localhost:3000处可访问

快速参考

根据IDE和个人偏好选择配置：

IDE	配置文件	格式选项
Claude桌面	`claude_desktop_config.json`	本地 ⭐ / Docker ✅
Claude代码	`.mcp.json`（项目根目录）	本地 ⭐ / Docker ✅
Cursor	`.cursor/mcp.json`	本地 ⭐ / Docker ✅

⭐ = 推荐 | ✅ = 完全工作

Claude桌面配置

编辑您的claude_desktop_config.json文件：

格式1：本地MCP服务器 ⭐ 推荐

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/绝对路径/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://localhost:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

重要：替换/绝对路径/to/mcp_excalidraw为您实际的安装路径。

格式2：Docker MCP服务器 ✅ 完全工作

使用GHCR上的预构建镜像（推荐）：

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

或者本地构建：

cd mcp_excalidraw
docker build -f Dockerfile -t mcp-excalidraw .

然后在上述配置中使用mcp-excalidraw作为镜像名称。

Claude代码配置

在项目根目录创建或编辑.mcp.json：

格式1：本地MCP服务器 ⭐ 推荐

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/绝对路径/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://localhost:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

重要：替换/绝对路径/to/mcp_excalidraw为您实际的安装路径。

格式2：Docker MCP服务器 ✅ 完全工作

使用GHCR上的预构建镜像（推荐）：

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

或者本地构建：

cd mcp_excalidraw
docker build -f Dockerfile -t mcp-excalidraw .

然后在上述配置中使用mcp-excalidraw作为镜像名称。

替代方案：使用Claude CLI

# 项目范围（推荐）
claude mcp add --scope project --transport stdio excalidraw \
  -- docker run -i --rm --network host \
  -e EXPRESS_SERVER_URL=http://localhost:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  mcp-excalidraw

# 用户范围（跨所有项目可用）
claude mcp add --scope user --transport stdio excalidraw \
  -- docker run -i --rm --network host \
  -e EXPRESS_SERVER_URL=http://localhost:3000 \
  -e ENABLE_CANVAS_SYNC=true \
  mcp-excalidraw

Cursor IDE配置

编辑.cursor/mcp.json：

格式1：本地MCP服务器 ⭐ 推荐

{
  "mcpServers": {
    "excalidraw": {
      "command": "node",
      "args": ["/绝对路径/to/mcp_excalidraw/dist/index.js"],
      "env": {
        "EXPRESS_SERVER_URL": "http://localhost:3000",
        "ENABLE_CANVAS_SYNC": "true"
      }
    }
  }
}

格式2：Docker MCP服务器 ✅ 完全工作

使用GHCR上的预构建镜像（推荐）：

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

或者本地构建：

cd mcp_excalidraw
docker build -f Dockerfile -t mcp-excalidraw .

然后在上述配置中使用mcp-excalidraw作为镜像名称。

重要配置说明

设置	目的	必需
`EXPRESS_SERVER_URL`	画布服务器URL	是（默认：http://localhost:3000）
`ENABLE_CANVAS_SYNC`	启用实时