Excalidraw MCP 服务器

根据自然语言生成精美的 Excalidraw 图表 — 完全本地化，无需云端 API。

你只需描述你的需求（例如“为电子商务应用绘制微服务架构图”），MCP 服务器就会调用你本地的 llama.cpp LLM，生成一个你可以立即打开的 .excalidraw 文件。

工作原理

You (Claude Desktop / Cursor)
        ↓  natural language description
  MCP Server (this project)
        ↓  structured prompt + Excalidraw JSON spec
  llama.cpp  (localhost:8080)
        ↓  raw Excalidraw JSON
  MCP Server  →  validates + saves  →  ~/excalidraw_diagrams/my-diagram.excalidraw
        ↓
  Open in Excalidraw

前置要求

要求	版本	备注
Python	≥ 3.11	`python3 --version`
uv	最新	`pip install uv` (推荐)
llama.cpp	最新	见第 1 步
GGUF 模型	推荐 7B+	见第 2 步
Excalidraw	Web 或本地	见第 5 步

设置

第 1 步 — 构建 llama.cpp

git clone https://github.com/ggerganov/llama.cpp
cd llama.cpp
cmake -B build
cmake --build build -j$(nproc)

在配备 Apple Silicon 的 macOS 上，添加 -DLLAMA_METAL=ON 以启用 GPU 加速。

第 2 步 — 下载 GGUF 模型

推荐模型（JSON 输出质量最佳）：

模型	大小	HuggingFace 路径
Qwen2.5-7B-Instruct (推荐)	~4.5 GB	`Qwen/Qwen2.5-7B-Instruct-GGUF`
Llama-3.1-8B-Instruct	~4.7 GB	`meta-llama/Meta-Llama-3.1-8B-Instruct-GGUF`
Mistral-7B-Instruct-v0.3	~4.1 GB	`mistralai/Mistral-7B-Instruct-v0.3-GGUF`

# Inside the llama.cpp directory:
mkdir models
# Download with huggingface-cli (pip install huggingface_hub):
huggingface-cli download Qwen/Qwen2.5-7B-Instruct-GGUF \
    qwen2.5-7b-instruct-q4_k_m.gguf \
    --local-dir models/

第 3 步 — 启动 llama.cpp 服务器

# From inside the llama.cpp directory:
./build/bin/llama-server \
    -m models/qwen2.5-7b-instruct-q4_k_m.gguf \
    --port 8080 \
    -c 8192 \
    --host 0.0.0.0

验证它是否正在运行：

curl http://localhost:8080/health
# → {"status":"ok"}

第 4 步 — 安装 MCP 服务器

# Clone this repo
git clone <repo-url>
cd exclalidraw_mcp

# Install with uv (recommended)
uv sync

# Or with pip
pip install -e .

验证 CLI 入口点是否正常工作：

excalidraw-mcp --help

第 5 步 — 配置你的 MCP 客户端

Claude Desktop (Linux)

编辑 ~/.config/claude/claude_desktop_config.json：

{
  "mcpServers": {
    "excalidraw": {
      "command": "excalidraw-mcp"
    }
  }
}

如果使用 uv，请将 "command": "excalidraw-mcp" 替换为：
"command": "uv",
"args": ["--directory", "/absolute/path/to/exclalidraw_mcp", "run", "excalidraw-mcp"]

Claude Desktop (macOS)

使用相同的内容编辑 ~/Library/Application Support/Claude/claude_desktop_config.json。

Cursor / VS Code

在你的 MCP 设置中添加上述相同的服务器配置。

编辑配置后重启应用程序。

第 6 步 — 在本地运行 Excalidraw（可选）

你可以随时免费使用 excalidraw.com。但若要完全在本地运行：

docker run -p 5000:80 excalidraw/excalidraw:latest
# Open http://localhost:5000

或通过 Node 运行：

npx excalidraw

使用方法

一旦 MCP 服务器连接成功，向你的 AI 客户端提问：

Generate a flowchart for a user login system with OAuth

Draw a microservices architecture for an e-commerce platform with cart, payment, and inventory services

Create a mind map about machine learning: supervised, unsupervised, reinforcement learning

Make a sequence diagram showing a REST API request from browser to server to database and back

Draw an ER diagram for a blog: users, posts, comments, tags

可用的 MCP 工具

工具	描述
`generate_diagram(description, diagram_type, filename)`	主要工具 — 根据文本生成图表
`check_llm_status()`	验证 llama.cpp 是否正在运行
`list_diagrams()`	列出所有已保存的图表

`generate_diagram` 参数

参数	类型	默认值	描述
`description`	string	必填	图表应展示的内容
`diagram_type`	string	`"flowchart"`	`flowchart`, `mindmap`, `sequence`, `architecture`, `erd`, `freeform`
`filename`	string	`"diagram"`	输出文件名（无需扩展名）

打开生成的图表

图表保存在 ~/excalidraw_diagrams/ 中。

打开 excalidraw.com 或你的本地实例
点击文件夹图标（左上角）→ 打开
选择你的 .excalidraw 文件

运行测试

# Install test dependencies
uv add --dev pytest pytest-anyio respx

# Run all tests
pytest tests/ -v

故障排除

“llama.cpp server is not running”

运行 curl http://localhost:8080/health。如果失败，请启动服务器（第 3 步）。

“Could not parse LLM output as valid Excalidraw JSON”

LLM 返回了格式错误的 JSON。尝试：

使用更好的模型（Qwen2.5-7B 或更大）
确保 llama.cpp 启动时使用了 -c 8192（足够的上下文）
先尝试简单的描述以验证流程是否正常

“图表看起来不对 / 缺少元素”

在描述中更具体一些
明确指定 diagram_type（例如使用 "flowchart" 而不是 "freeform"）
更大的模型（13B+）能产生明显更好的布局

工具未在 Claude Desktop 中显示

确认 claude_desktop_config.json 没有 JSON 语法错误
完全重启 Claude Desktop
检查日志：~/.config/claude/logs/ (Linux) 或 ~/Library/Logs/Claude/ (macOS)

项目结构

exclalidraw_mcp/
├── src/excalidraw_mcp/
│   ├── server.py       ← MCP server + tool definitions
│   ├── llm_client.py   ← llama.cpp HTTP client
│   ├── generator.py    ← Prompt building + JSON parsing + validation
│   └── schema.py       ← Excalidraw element dataclasses
├── prompts/
│   └── examples/       ← Few-shot example diagrams (flowchart, mindmap, sequence)
├── examples/
│   └── sample.excalidraw  ← Reference diagram you can open immediately
├── tests/
│   ├── test_generator.py
│   └── test_llm_client.py
├── pyproject.toml
└── README.md

制作更好图表的技巧

具体化：“带有电子邮件/密码、JWT 令牌和会话存储的登录流程”比“登录流程”更好
命名元素：“标记为 A、B、C 并用箭头连接的方框” → Excalidraw 会遵循你的命名
指定颜色：“服务使用蓝色，数据库使用黄色”
保持专注：每个图表展示一个逻辑概念比试图展示所有内容效果更好
自由重新生成：如果第一次结果不完美，请使用不同的文件名再次询问 — 它是即时的

许可证

MIT

Excalidraw MCP Server

Excalidraw MCP 服务器

工作原理

前置要求

设置

第 1 步 — 构建 llama.cpp

第 2 步 — 下载 GGUF 模型

第 3 步 — 启动 llama.cpp 服务器

第 4 步 — 安装 MCP 服务器

第 5 步 — 配置你的 MCP 客户端

Claude Desktop (Linux)

Claude Desktop (macOS)

Cursor / VS Code

第 6 步 — 在本地运行 Excalidraw（可选）

使用方法

可用的 MCP 工具

`generate_diagram` 参数

打开生成的图表

运行测试

故障排除

“llama.cpp server is not running”

“Could not parse LLM output as valid Excalidraw JSON”

“图表看起来不对 / 缺少元素”

工具未在 Claude Desktop 中显示

项目结构

制作更好图表的技巧

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

Excalidraw MCP 服务器

工作原理

前置要求

设置

第 1 步 — 构建 llama.cpp

第 2 步 — 下载 GGUF 模型

第 3 步 — 启动 llama.cpp 服务器

第 4 步 — 安装 MCP 服务器

第 5 步 — 配置你的 MCP 客户端

Claude Desktop (Linux)

Claude Desktop (macOS)

Cursor / VS Code

第 6 步 — 在本地运行 Excalidraw（可选）

使用方法

可用的 MCP 工具

generate_diagram 参数

打开生成的图表

运行测试

故障排除

“llama.cpp server is not running”

“Could not parse LLM output as valid Excalidraw JSON”

“图表看起来不对 / 缺少元素”

工具未在 Claude Desktop 中显示

项目结构

制作更好图表的技巧

许可证

Resources

Looking for Admin?

Tools

Latest Blog Posts

MCP directory API

`generate_diagram` 参数