1. 项目概述一个连接AI与绘图的“翻译官”最近在折腾AI应用开发特别是想让大语言模型LLM能直接操作一些专业工具比如画图。我发现了一个挺有意思的项目yctimlin/mcp_excalidraw。简单来说它是一个MCPModel Context Protocol服务器专门为Excalidraw这个开源的白板绘图工具提供AI操作接口。你可以把它理解成一个“翻译官”。大语言模型比如ChatGPT、Claude本身不懂怎么直接操作Excalidraw的界面或API它们只会“说话”发送和接收结构化的文本或JSON。而这个MCP服务器就负责把AI的“想法”比如“画一个红色的圆”翻译成Excalidraw能听懂的指令并执行绘图操作然后再把结果比如一张新图的链接翻译回AI能理解的格式。这样一来AI就仿佛拥有了“手”可以直接在数字白板上进行创作、修改图表、绘制架构图等。这个项目解决的痛点非常明确让AI驱动的应用或智能体Agent具备可视化绘图能力。无论是自动生成会议草图、根据描述创建流程图还是在对话中实时修改图表都成为了可能。它把Excalidraw强大的、易于协作的绘图能力变成了AI工具箱里的一个标准件。2. MCP协议与Excalidraw核心组件解析要理解这个项目得先拆开看看它的两大基石MCP协议和Excalidraw。2.1 Model Context Protocol (MCP)AI的“外设”标准接口MCP是Anthropic提出的一种协议你可以把它想象成电脑的USB标准。在没有USB之前每个外设打印机、鼠标都需要自己的驱动和接口非常混乱。MCP的目标就是为LLM定义一个标准的“外设”接口。核心思想是让LLM客户端能够通过一个标准化的方式发现、调用外部工具服务器提供的功能并获取结构化的结果。一个MCP服务器可以提供三类资源工具Tools可供LLM调用的函数比如“画一个矩形”、“获取当前图纸”。提示词模板Prompts预定义的对话模板方便LLM快速发起特定类型的交互。资源Resources可供LLM读取的静态或动态数据比如“系统状态文档”。mcp_excalidraw就是一个实现了MCP协议的服务器它向LLM客户端如Claude Desktop、自定义的AI应用暴露了一系列操作Excalidraw的“工具”。注意MCP是一个相对较新的协议生态还在发展中。使用它意味着你需要一个支持MCP的客户端。目前Claude Desktop原生支持你也可以在自行开发的AI应用中使用MCP客户端库如TypeScript的modelcontextprotocol/sdk来连接这类服务器。2.2 Excalidraw为何是它Excalidraw是一个开源的虚拟白板用于绘制手绘风格的图表。它之所以成为这个项目的首选有几个关键原因开源且可自托管你可以完全控制数据和部署这对于需要处理敏感信息或希望深度定制的场景至关重要。mcp_excalidraw项目通常需要与一个Excalidraw实例配合使用。API友好Excalidraw提供了丰富的ExcalidrawElement数据结构和序列化格式.excalidraw或.excalidrawlib文件便于程序化生成和修改图形。它的状态所有图形元素、背景、视图位置可以用一个JSON对象完整描述。手绘美感其输出的图形带有自然的手绘抖动效果比标准几何图形看起来更亲切、更具创意非常适合脑图、草图、架构示意图。活跃的社区作为一款流行工具其文档、示例和第三方集成比较丰富降低了开发难度。项目核心原理mcp_excalidraw服务器启动后会作为一个独立的进程运行。它内部会维护一个或多个Excalidraw“场景”可以理解为画布实例。当LLM客户端通过MCP协议调用其提供的工具如create_drawing时服务器会解析工具参数图形类型、位置、样式等。在内存中构建或更新对应的Excalidraw元素数据结构。将更新后的场景状态序列化为Excalidraw可识别的格式如生成一个包含场景数据的URL或直接返回JSON。将这个结果通常是一个可访问的URL通过MCP协议返回给LLM客户端。这样用户或AI应用就能通过这个URL看到最新绘制的图形。3. 部署与配置实战让服务器跑起来理论清楚了接下来我们动手把它部署起来。这里假设你已经在本地或服务器上准备好了基本的Python环境。3.1 环境准备与依赖安装项目是基于Python的所以第一步是克隆代码和安装依赖。# 克隆项目仓库 git clone https://github.com/yctimlin/mcp_excalidraw.git cd mcp_excalidraw # 创建并激活虚拟环境推荐 python -m venv venv # 在Windows上: venv\Scripts\activate # 在macOS/Linux上: source venv/bin/activate # 安装项目依赖 pip install -r requirements.txtrequirements.txt里通常会包含mcpMCP服务器SDK、fastapi用于提供HTTP服务、uvicornASGI服务器等核心库。安装过程一般很顺利。实操心得强烈建议使用虚拟环境。这能避免Python包版本冲突尤其是在你本地可能运行着其他AI项目时。如果安装过程中遇到某个包版本问题可以尝试先单独安装mcp的最新版再安装其他依赖。3.2 服务器配置详解项目根目录下通常会有一个配置文件如config.yaml或.env文件或需要通过环境变量进行配置。关键配置项包括Excalidraw实例地址(EXCALIDRAW_URL) 这是最重要的配置。你需要指定mcp_excalidraw服务器将图形数据发送到哪个Excalidraw前端进行渲染。使用官方托管版可以设置为https://excalidraw.com。但注意这会将你的图形数据发送到公共网络不适合敏感内容。使用自托管实例这是推荐的生产环境做法。你需要自己部署一个Excalidraw很简单通常就是运行一个Docker容器或静态服务然后将地址配置为此处例如http://localhost:3000或https://draw.your-company.com。服务器监听端口(SERVER_PORT) MCP服务器本身需要在一个端口上运行等待客户端连接。默认可能是8000。认证与安全 如果自托管Excalidraw并配置了访问密码或者你希望为MCP服务器本身添加简单的认证可能需要配置相关的Token或密钥。初期测试可以暂不配置。一个典型的启动命令或配置片段如下# config.yaml 示例 server: host: 0.0.0.0 port: 8000 excalidraw: base_url: http://localhost:3000 # 指向你的自托管Excalidraw # room_id: optional-room-id # 如果需要多房间协作可以指定或者通过环境变量启动export EXCALIDRAW_BASE_URLhttp://localhost:3000 export SERVER_PORT8000 python main.py3.3 连接MCP客户端以Claude Desktop为例服务器跑起来后需要让一个MCP客户端知道它。这里以最常用的Claude Desktop为例。找到Claude Desktop的MCP配置文件。位置通常如下macOS:~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:%APPDATA%\Claude\claude_desktop_config.json编辑这个JSON文件添加你的mcp_excalidraw服务器配置。文件结构大致如下{ mcpServers: { excalidraw: { command: /absolute/path/to/your/venv/bin/python, args: [ /absolute/path/to/mcp_excalidraw/main.py ], env: { EXCALIDRAW_BASE_URL: http://localhost:3000 } } } }关键点command必须是你虚拟环境中Python解释器的绝对路径。args是你的main.py脚本的绝对路径。env在这里传递环境变量覆盖或设置服务器配置。保存配置文件完全重启Claude Desktop。重启后在Claude的聊天界面你应该能看到一个新的工具图标比如一个画笔或者当你在对话中提到“画图”时Claude会主动提示可以使用Excalidraw工具。踩坑记录配置文件路径错误或权限问题是导致连接失败的最常见原因。确保路径完全正确并且Claude Desktop有权限执行该Python命令。第一次配置后务必彻底退出并重启Claude Desktop仅仅关闭窗口可能不够。4. 核心工具使用与场景示例服务器和客户端连接成功后我们就可以看看AI能通过它具体做哪些事情了。mcp_excalidraw暴露的工具是其核心价值所在。4.1 基础绘图工具解析通常服务器会提供以下几类基础工具1. 创建新绘图 (create_drawing或initialize_canvas)功能初始化一个全新的画布。参数可能包括画布背景色、初始视图缩放、名称等。AI调用示例当用户说“新建一个白板来讨论系统架构”时AI可以调用此工具返回一个新画布的链接。2. 添加图形元素 (add_element)功能向当前活动的画布添加特定图形。参数这是一个复杂的参数集体现了Excalidraw元素的丰富性。type:rectangle,ellipse,diamond,line,arrow,text等。x,y: 元素左上角或起点的坐标。width,height: 元素的尺寸。strokeColor: 边框颜色十六进制如#FF0000。backgroundColor: 填充颜色。strokeWidth: 边框粗细。roundness: 圆角程度用于矩形、菱形等赋予手绘感。text: 如果类型是text则包含文本内容。points: 对于折线或自由绘制是一系列[x, y]坐标点。AI调用逻辑AI需要将自然语言描述解析为这些结构化参数。例如“在中间画一个蓝色的圆”会被解析为type: ellipse,backgroundColor: #0000FF,x,y,width,height需要根据画布大小计算居中位置。3. 修改元素 (modify_element)功能更改已有元素的属性。参数需要指定元素的id在创建时由系统生成或返回以及要修改的属性键值对。场景用户说“把那个矩形改成红色并加大”AI需要先通过上下文或追问确定是哪个矩形对应id然后调用此工具更新strokeColor和width/height。4. 获取绘图状态 (get_drawing或export_drawing)功能导出当前画布的状态。返回通常是一个Excalidraw格式的JSON数据或者一个包含了该数据的可分享URL。用途AI可以在完成一系列操作后调用此工具获取最终成果的链接展示给用户。4.2 典型应用场景演练让我们模拟几个完整的对话流看看AI如何协同这些工具工作。场景一快速绘制流程图用户帮我画一个简单的用户登录流程图。 AI思考需要创建画布然后添加“开始”、“输入密码”、“验证”、“成功/失败”、“结束”等文本框并用箭头连接它们。 AI行动 1. 调用 create_drawing设置画布名称为“登录流程图”。 2. 循环调用 add_element依次创建多个type: text的元素计算好它们的位置比如垂直排列。 3. 调用 add_elementtype: arrow通过points参数在上一步的文本框之间绘制连接线。 4. 调用 get_drawing将生成的URL返回给用户。用户看到一个打开即用的、手绘风格的登录流程图草图。场景二在对话中修改图表用户在一个已有架构图的对话中把数据库组件标成黄色高亮。 AI思考我需要找到代表“数据库”的那个图形元素。可能通过之前的上下文我知道它的ID或者我需要先描述性定位比如“那个在右下角的圆柱体”。假设我知道ID是element_123。 AI行动 1. 调用 modify_element参数为 id: element_123, backgroundColor: #FFFF00。 2. 调用 get_drawing返回更新后的链接。用户看到原图中的数据库组件瞬间变成了亮黄色。场景三基于文本描述生成草图用户画一个太阳系示意图太阳在中间周围有地球和火星的轨道。 AI思考这需要更复杂的空间布局计算。太阳是一个大的黄色圆地球和火星是较小的圆它们的轨道是椭圆形的虚线。 AI行动 1. create_drawing 创建画布。 2. add_element 画一个大黄色椭圆作为太阳定位在画布中心。 3. 计算地球轨道的椭圆参数用add_element画一个type: ellipse但设置fillStyle: none, strokeStyle: dashed作为轨道。 4. 在地球轨道上某点画一个蓝色小圆作为地球。 5. 同理为火星添加轨道和红色小圆。 6. get_drawing 返回结果。这个场景对AI的空间理解和参数计算能力要求较高展示了MCP将复杂认知任务转化为具体执行动作的潜力。5. 高级技巧与自定义开发基础使用能满足很多场景但要想发挥更大威力或者将其集成到自己的应用中就需要深入了解一些高级特性和开发模式。5.1 工具能力的扩展与组合默认的工具集可能只覆盖了Excalidraw的部分功能。你可以通过修改mcp_excalidraw的源代码来扩展工具。例如Excalidraw支持“帧”Frame元素来分组内容但默认工具可能没有暴露。你可以在服务器的工具定义文件比如tools.py中新增一个create_frame工具。在该工具的实现函数里按照Excalidraw的Frame元素数据结构构造对应的JSON。重新启动MCP服务器Claude Desktop就会自动发现这个新工具。更高级的用法是创建“复合工具”。比如你可以创建一个create_flowchart_node工具它内部不仅创建一个矩形还会自动在矩形内部居中添加文字标签。这样AI只需要调用一次就能完成一个节点的创建提高了效率和指令的简洁性。5.2 状态管理与多画布支持一个关键的实现细节是状态管理。MCP服务器通常是无状态的但绘图需要维持画布上所有元素的状态。内存状态最简单的实现是服务器在内存中维护一个字典以drawing_id为键存储整个画布的元素列表。当客户端AI进行操作时必须指定或在上下文中隐含drawing_id。这种方式简单但服务器重启后状态丢失。持久化存储更健壮的方式是将画布状态保存到数据库如SQLite、PostgreSQL或文件系统中。每次工具调用都进行读写。这样即使服务器重启也能恢复之前的绘图。多画布/多房间支持多个独立的画布实例。这需要工具接口中包含room_id或drawing_id参数。这对于构建多用户协作AI应用例如每个会议频道一个独立白板是必需的。在mcp_excalidraw的代码中你会找到一个管理画布状态的类可能叫DrawingManager或SessionStore。理解它的设计是进行自定义扩展的基础。5.3 集成到自定义AI应用你不必局限于Claude Desktop。任何能够扮演MCP客户端的应用都可以使用它。前端集成示例假设你有一个React Web应用希望内置一个AI助手来辅助绘图。在你的后端服务可以是Node.js、Python等中集成一个MCP客户端库并配置它连接到你自己部署的mcp_excalidraw服务器。当用户在前端输入“画个笑脸”时前端将请求发送给你的后端。后端使用LLM调用OpenAI API或本地模型处理用户消息LLM决定调用excalidraw.add_element工具。后端MCP客户端执行这个工具调用从mcp_excalidraw服务器获取到更新后的画布URL或数据。后端将URL或数据返回给前端。前端更新Excalidraw组件如果你直接集成了Excalidraw React组件或跳转到新URL展示结果。技术栈选择MCP客户端SDKAnthropic官方提供了TypeScript/JavaScript和Python的SDK这是最规范的选择。LLM调用可以使用LangChain、LlamaIndex等框架来更优雅地管理工具调用和LLM交互。Excalidraw嵌入强烈建议使用excalidraw/excalidrawnpm包将Excalidraw作为组件嵌入你的应用这样可以实现无缝的界面集成和更精细的控制而不是仅仅跳转链接。6. 常见问题与故障排查在实际部署和使用过程中你肯定会遇到一些问题。这里总结了一些常见坑点和解决方法。6.1 连接与配置问题问题1Claude Desktop中看不到Excalidraw工具图标。检查步骤配置文件确认claude_desktop_config.json格式正确路径无拼写错误。JSON语法是否有效可以先用在线校验工具检查。路径问题command和args中的路径必须是绝对路径。使用which python或where pythonon Windows和pwd命令来获取准确路径。服务器日志在终端手动运行你的MCP服务器启动命令如python main.py查看是否有错误输出。常见的错误包括端口被占用、依赖包缺失、配置文件读取失败。重启Claude必须完全退出并重启Claude Desktop。在macOS上可能需要从Dock强制退出。环境变量确保在配置文件的env字段或服务器启动环境中正确设置了EXCALIDRAW_BASE_URL。问题2AI调用工具后返回错误或没有反应。检查步骤服务器日志查看MCP服务器的运行日志这是最重要的调试信息源。工具调用时的参数错误、Excalidraw实例连接失败都会在这里体现。Excalidraw实例确认你配置的EXCALIDRAW_BASE_URL可以正常访问。在浏览器中打开这个地址应该能看到Excalidraw的界面。工具参数AI有时会生成不合法的参数如颜色格式错误、坐标超出范围。查看日志中AI发送的具体参数尝试在代码中为工具参数添加更严格的验证和默认值。6.2 性能与稳定性优化问题3绘图操作有延迟或复杂图形生成慢。原因与优化网络延迟如果MCP服务器、Excalidraw实例和客户端分布在不同的网络环境每次工具调用都会产生多次网络往返。尽量将它们部署在同一内网或低延迟的区域。批量操作默认工具可能一次只操作一个元素。绘制一个由多个元素组成的复杂图形时AI需要连续调用多次工具产生大量通信。可以考虑开发“批量添加元素”的工具接受一个元素数组减少调用次数。状态同步每次操作后都调用get_drawing获取完整状态可能会返回大量数据。如果只是需要确认操作成功可以让工具返回一个更轻量的响应如成功状态和受影响元素的ID仅在需要展示时才获取完整数据。问题4服务器重启后之前的绘图丢失了。解决方案如前所述实现状态的持久化。修改代码将DrawingManager中内存里的画布数据在每次变更时保存到SQLite数据库或一个JSON文件中。服务器启动时从持久化存储中加载所有画布状态。6.3 安全与权限考量问题5如何防止他人滥用我的MCP服务器基础防护不要暴露公网初期测试时MCP服务器和Excalidraw实例最好都在本地运行localhost。如果必须远程访问使用SSH隧道。添加认证MCP协议支持服务器认证。你可以在服务器启动时要求提供API密钥并在客户端配置中附带该密钥。这需要修改服务器代码在工具调用前验证密钥。限制工具在代码中移除或禁用可能存在风险的工具例如如果存在delete_drawing工具在公开环境中可以考虑注释掉。生产环境部署考虑将整套系统MCP服务器、Excalidraw、你的AI应用后端部署在私有VPC内通过API网关或反向代理如Nginx对外提供有限的、受认证的访问端点而不是直接暴露MCP服务器的原始端口。7. 项目演进与生态展望yctimlin/mcp_excalidraw作为一个开源项目其价值不仅在于当前的功能更在于它展示了一种范式通过标准化协议MCP为LLM赋予操作复杂专业软件的能力。可能的演进方向工具集丰富化除了基本图形未来可以集成Excalidraw的更多高级功能如激光笔指示、多人光标显示、导入图片作为背景、更复杂的图形库.excalidrawlib管理等。智能体Agent专用优化针对AutoGPT、CrewAI等多智能体框架进行优化例如提供更好的并发绘图状态管理、冲突解决机制当多个AI试图修改同一元素时。与其他MCP服务器联动想象一下一个AI可以同时调用mcp_excalidraw画图、调用mcp_github管理代码、调用mcp_slack发送消息。这构成了一个真正全能AI助手的工作流。项目的配置可以更容易地与其他MCP服务器组合使用。对开发者的启示 这个项目是一个极佳的MCP协议学习样板。如果你有一个希望被AI操作的工具或服务比如内部CMS、数据分析平台参照mcp_excalidraw的代码结构你可以快速构建出自己的MCP服务器。核心就是定义工具输入输出Schema、实现工具函数调用你的服务API、运行MCP服务器。我个人在尝试将它与自研的文档系统结合时发现最大的挑战不在于技术实现而在于如何设计“工具”的粒度。工具太细如“移动元素1像素”AI调用起来低效且容易混乱工具太粗如“画一个完整的架构图”实现起来复杂且不灵活。mcp_excalidraw在“添加元素”、“修改元素”这个粒度上找到了一个不错的平衡点既保持了灵活性又让AI能够相对容易地理解和组合使用。这或许是设计任何AI可调用工具时都需要深思熟虑的一点。