Name: 实时可视化图表AI集成工具
Author: Fromsko

使用说明

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

📦 这是由维护的fork和npm包版本 @弗罗姆斯科
🙏 原始项目由 @yctimlin
📋 包名称： @fromsko/excalidraw-mcp-server

全面 基于TypeScript 系统结合 Excalidraw强大的绘图功能 随着 模型上下文协议（MCP） 集成，使AI代理能够在实时画布上实时创建和操纵图表。

🚦 当前状态和版本信息

📋 选择您的安装方法

版本	状态	建议用于
地方发展	✅ 经过全面测试	🎯 推荐
NPM发布	🔧 调试正在进行中	开发测试
Docker版本	🔧 开发中	未来部署

当前建议：地方发展

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

开发说明

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

🚀 这个系统做什么

🎨 实时画布：可通过web浏览器访问实时Excalidraw画布
🤖 人工智能集成：MCP服务器允许AI代理（如Claude）创建可视化图表
⚡ 实时同步：通过MCP API创建的元素立即出现在画布上
🔄 WebSocket更新：跨多个连接的客户端进行实时同步
🏗️ 生产就绪：适合最终用户的干净、简洁的UI

🎥 演示视频

请参阅MCP豁免行动！

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

🏛️ 架构概述

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AI Agent      │───▶│   MCP Server     │───▶│  Canvas Server  │
│   (Claude)      │    │  (src/index.js) │    │ (src/server.js) │
└─────────────────┘    └──────────────────┘    └─────────────────┘
                                                         │
                                                         ▼
                                               ┌─────────────────┐
                                               │  Frontend       │
                                               │  (React + WS)   │
                                               └─────────────────┘

🌟 主要特点

现代TypeScript架构

完全TypeScript迁移：后端和前端的完全类型安全
综合类型定义：Excalidraw元素、API响应、WebSocket消息
严格类型检查：增强开发体验和编译时错误检测
类型安全反应组件：TSX组件具有正确的props类型

实时Canvas集成

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

生产就绪界面

干净、简洁的UI，带有连接状态
简单的“透明画布”功能
无开发混乱或调试信息

综合MCP API

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

稳健的体系结构

基于TypeScript-based Express.js后端，带有REST API+WebSocket
使用官方Excalidraw包和TypeScript的React前端
双路径元件加载，提高可靠性
自动重新连接和错误处理

📦 安装和设置

✅ 推荐：本地开发设置

最稳定、功能最齐全的选项

1.克隆存储库

git clone https://github.com/fromsko/excalidraw-mcp-server.git
cd excalidraw-mcp-server
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包（@fromsko/excalidraw mcp服务器）

# Install globally
npm install -g @fromsko/excalidraw-mcp-server

# Or run directly
npx @fromsko/excalidraw-mcp-server

Docker版本（即将推出）

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

🔧 可用脚本

脚本	描述
`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服务器提供以下工具用于创建可视化图表：

基本元素创建

// 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/dist/index.js"]
		}
	}
}

重要：替换 /absolute/path/to/excalidraw-mcp-server 使用克隆存储库的实际绝对路径。请注意，路径现在指向 dist/index.js （编译后的TypeScript输出）。

🔧 替代配置（测试版）

NPM包（@fromsko/excalidraw mcp服务器）

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

Docker版本（即将推出）

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

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

🔧 与其他工具集成

光标IDE

添加到您的 .cursor/mcp.json:

{
	"mcpServers": {
		"excalidraw": {
			"command": "node",
			"args": ["/absolute/path/to/excalidraw-mcp-server/dist/index.js"]
		}
	}
}

VS代码MCP扩展

对于VS Code MCP扩展，请添加到您的设置中：

{
	"mcp": {
		"servers": {
			"excalidraw": {
				"command": "node",
				"args": ["/absolute/path/to/excalidraw-mcp-server/dist/index.js"]
			}
		}
	}
}

🛠️ 环境变量

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

📊 API终点

canvas服务器提供以下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+TypeScript：具有全类型安全性的现代TSX组件
Vite构建系统：快速开发和优化生产构建
官方豁免: @excalidraw/excalidraw 带有TypeScript类型的包
WebSocket客户端：类型安全实时元素同步
干净的UI：具有正确TypeScript类型的生产就绪接口

Canvas服务器 (`src/server.ts` → `dist/server.js`)

TypeScript+Express.js：完全类型的REST API+静态文件服务
网络套接字：类型安全的实时客户端通信
元素存储：具有全面类型定义的内存
CORS：具有正确键入的跨源支持

MCP服务器 (`src/index.ts` → `dist/index.js`)

TypeScript MCP协议：类型安全模型上下文协议实现
画布同步：对canvas服务器的强类型HTTP请求
网元管理：具有全面类型检查的完整CRUD操作
批量支持：类型安全复杂图创建

类型系统 (`src/types.ts`)

排除元素类型：所有元素类型的完整类型定义
API响应类型：强类型REST API接口
WebSocket消息类型：类型安全实时通信
服务器元素类型：使用元数据增强元素类型

🐛 故障排除

NPM包问题

症状：MCP工具未正确注册
权宜之计：使用本地开发设置
状态：正在调试-更新即将到来

Docker版本说明

症状：元素可能不会立即同步到画布
权宜之计：使用本地开发设置
状态：提高同步可靠性

画布未加载

确保 npm run build 已成功完成
检查一下 dist/index.html 存在
验证canvas服务器是否在端口3000上运行

元素不同步

确认MCP服务器正在运行(npm start)
检查 ENABLE_CANVAS_SYNC=true 在环境中
验证canvas服务器是否可访问 EXPRESS_SERVER_URL

WebSocket连接问题

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

构建错误

删除 node_modules 然后跑 npm install
检查Node.js版本（需要16+）
确保安装了所有依赖项
跑 npm run type-check 识别TypeScript问题
验证 dist/ 目录创建于 npm run build:server

📋 项目结构

excalidraw-mcp-server/
├── frontend/
│   ├── src/
│   │   ├── App.tsx          # Main React component (TypeScript)
│   │   └── main.tsx         # React entry point (TypeScript)
│   └── index.html           # HTML template
├── src/ (TypeScript Source)
│   ├── index.ts            # MCP server (TypeScript)
│   ├── server.ts           # Canvas server (Express + WebSocket, TypeScript)
│   ├── types.ts            # Comprehensive type definitions
│   └── utils/
│       └── logger.ts       # Logging utility (TypeScript)
├── dist/ (Compiled Output)
│   ├── index.js            # Compiled MCP server
│   ├── server.js           # Compiled Canvas server
│   ├── types.js            # Compiled type definitions
│   ├── utils/
│   │   └── logger.js       # Compiled logging utility
│   └── frontend/           # Built React frontend
├── tsconfig.json          # TypeScript configuration
├── vite.config.js         # Vite build configuration
├── package.json           # Dependencies and scripts
└── README.md              # This file

🔮 发展路线图

✅ TypeScript迁移：完全类型安全，增强开发体验
NPM包：解决MCP工具注册问题
Docker部署：改进画布同步
增强功能：附加MCP工具和功能
性能优化：实时同步改进
TypeScript高级功能：更严格的类型检查和高级类型实用程序

🤝 贡献

我们欢迎捐款！如果您遇到NPM包或Docker版本的问题，请：

🙏 致谢

原作者: @yctimlin -感谢您创建这个令人惊叹的项目！
原始存储库: mcp_excalidraw
驱逐队：对于梦幻般的绘图库
MCP社区：用于模型上下文协议

📜 贡献者

@yctimlin -原创者和开发者
@弗罗姆斯科 -包维护者和fork贡献者

📝 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

备注这是yctimlin原始项目的一个分支。原始实现的所有功劳都归功于原作者。

分叉存储库
创建要素分支(git checkout -b feature/amazing-feature)
提交您的更改(git commit -m 'Add amazing feature')
推到分支(git push origin feature/amazing-feature)
打开拉取请求

📝 许可证

此项目根据MIT许可证获得许可-请参阅许可证文件以获取详细信息。

🙏 致谢

驱逐队 -对于惊人的绘图库
MCP社区 -对于模型上下文协议规范

使用说明

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

🚦 当前状态和版本信息

当前建议：地方发展

开发说明

🚀 这个系统做什么

🎥 演示视频

🏛️ 架构概述

🌟 主要特点

现代TypeScript架构

实时Canvas集成

生产就绪界面

综合MCP API

稳健的体系结构

📦 安装和设置

✅ 推荐：本地开发设置

1.克隆存储库

2.构建前端

3.启动系统

选项A：生产模式（推荐）

方案B：开发模式

4.访问画布

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

NPM包（@fromsko/excalidraw mcp服务器）

Docker版本（即将推出）

🔧 可用脚本

🎯 使用指南

面向最终用户

AI代理（通过MCP）

基本元素创建

创建文本元素

创建箭头和线条

复杂图表的批量创建

🔌 与Claude Desktop集成

✅ 推荐：使用本地安装

🔧 替代配置（测试版）

NPM包（@fromsko/excalidraw mcp服务器）

Docker版本（即将推出）

🔧 与其他工具集成

光标IDE

VS代码MCP扩展

🛠️ 环境变量

📊 API终点

🎨 MCP工具可用

网元管理

批量操作

要素组织

资源访问

🏗️ 开发结构

前端 (frontend/src/)

Canvas服务器 (src/server.ts → dist/server.js)

MCP服务器 (src/index.ts → dist/index.js)

类型系统 (src/types.ts)

🐛 故障排除

NPM包问题

Docker版本说明

画布未加载

元素不同步

WebSocket连接问题

构建错误

📋 项目结构

🔮 发展路线图

🤝 贡献

🙏 致谢

📜 贡献者

📝 许可证

📝 许可证

🙏 致谢

相关 MCP

Excalidraw MCP服务器

Markdown转思维导图服务

AntV文档协议服务器

图表生成服务

代码代理管理工具

Monorepo可视化工具

前端 (`frontend/src/`)

Canvas服务器 (`src/server.ts` → `dist/server.js`)

MCP服务器 (`src/index.ts` → `dist/index.js`)

类型系统 (`src/types.ts`)