en ja ru zh

Excalidraw MCP Server

Name: Excalidraw MCP Server
Author: jeel00dev

by jeel00dev

Overview Schema Source Related Servers Discussions Admin

Local

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

Related MCP server: Excalidraw MCP App Server

前置要求

要求	版本	备注
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

Available Tools

3 tools

check_llm_statusA

Check whether the local llama.cpp server is running and reachable.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. The description indicates a read-only check operation, but does not describe behavior like timeout, error handling, or what constitutes 'reachable'. However, it is not misleading.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

A single sentence that conveys the full purpose with no extraneous words. It is front-loaded and efficient.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters and the existence of an output schema, the description is mostly complete. It could mention the expected return value format (e.g., boolean or status object), but the output schema presumably covers that.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, so schema coverage is 100%. The description adds meaning beyond the schema by explaining the tool's purpose. With zero parameters, baseline is 4.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the tool checks if a local llama.cpp server is running and reachable. It uses a specific verb ('check') and resource ('local llama.cpp server'). This purpose is distinct from sibling tools (generate_diagram, list_diagrams).

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or alternatives. The context implies usage before other server-dependent tools, but the description does not state this. No exclusions or alternatives are given.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

generate_diagramA

Generate an Excalidraw diagram from a natural-language description.

Args: description: What the diagram should show, e.g. "user login flow with OAuth and MFA" diagram_type: One of: flowchart, mindmap, sequence, architecture, erd, freeform filename: Output filename without extension (saved to ~/excalidraw_diagrams/)

ParametersJSON Schema

Name	Required	Default
`description`	Yes
`diagram_type`	No	flowchart
`filename`	No	diagram

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A3.8/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided, so description carries burden. Discloses save location (~/excalidraw_diagrams/) and allowed diagram types, but lacks details on overwrite behavior, permissions, or side effects.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness4/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Concise docstring format with front-loaded purpose. No redundant information, but the Args section somewhat duplicates the schema.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Covers key aspects: purpose, parameters, output location, example. But missing behavioral details like file overwrite, error handling, and output format (though output schema exists but unknown).

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema has 0% coverage, so description compensates well: explains description parameter with example, lists diagram_type options, and clarifies filename extension and save location. Could be more precise about allowed diagram_type values.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it generates an Excalidraw diagram from natural language, with an example. Distinguishes from siblings (check_llm_status, list_diagrams) by being the only diagram generation tool.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implied usage from description, but no explicit when-to-use or when-not-to-use guidance. No comparisons with alternatives, though siblings are unrelated.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

list_diagramsA

List all Excalidraw diagrams previously generated by this server.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.5/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It discloses that the tool lists diagrams previously generated by this server, implying read-only behavior. However, it does not elaborate on ordering, pagination (if any), or authorization. Given the tool's simplicity, this is adequate.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single sentence that immediately conveys the tool's purpose. It is concise and front-loaded with no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given zero parameters and an existing output schema, the description provides all necessary information for an agent to understand and invoke the tool correctly. It is complete for its complexity.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are zero parameters, and schema coverage is 100%. The description has no need to explain parameters. Per guidelines, a baseline of 4 is appropriate for tools with no parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb ('list') and resource ('all Excalidraw diagrams previously generated by this server'). It distinguishes from sibling tools: generate_diagram creates diagrams, check_llm_status checks LLM status, so there is no ambiguity.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Although the description does not explicitly state when to use this tool versus alternatives, the context makes it obvious: it lists all diagrams, while siblings create or check status. The simplicity means the purpose is self-evident, but a slight lack of explicit guidance prevents a 5.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

3 tool updatesv0.1.0May 5, 2026
- First observedcheck_llm_status
- First observedgenerate_diagram
- First observedlist_diagrams

Deploy Server

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

A4.2/5.0

Scored 2026-05-05 07:15 across 3 tools

Disambiguation5/5

Each tool has a clear, non-overlapping purpose: checking server status, generating a diagram, and listing previously generated diagrams. No ambiguity in choosing which tool to use.

Naming Consistency5/5

All tool names follow a consistent verb_noun pattern in snake_case (check_llm_status, generate_diagram, list_diagrams), making them predictable and easy to understand.

Tool Count5/5

With only 3 tools, the server is tightly focused on diagram generation and management. Each tool serves a distinct need without unnecessary bloat, perfectly scoped for its purpose.

Completeness4/5

The core workflows are covered: health check, diagram creation, and listing past diagrams. Missing deletion is a minor gap, but the server still fulfills its primary function effectively.

Maintenance

ActivityStale

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Related MCP Connectors

LetDraw
io.github.letdraw
Create, edit, share and export hand-drawn LetDraw diagrams, from code or a prompt.
Design Tools Software Architecture
1
Super ExcalidrawOAuth
io.github.Si40Code
Create editable Excalidraw diagrams with AI and an interactive MCP Apps canvas. OAuth sign-in.
1
ExcaliClawOAuth
com.excaliclaw
Create, edit and organize hand-drawn diagrams (flowcharts, ER, architecture) from any AI agent.
Software Architecture Design Tools
1
Flowgraf A
in.flowgraf
Create and edit architecture diagrams from your AI agent; get an SVG and a live editable canvas.
Software Architecture Design Tools
2

Related MCP Servers

Excalidraw MCP Server
Developer Tools File Systems Image & Video Processing
andreswebs-public-images
A
license
A
quality
D
maintenance
Enables creation, management, and export of Excalidraw drawings through natural language. Supports CRUD operations on drawings and export to SVG, PNG, and JSON formats with file-based storage.
Updated 10 months ago (2025-11-24 18:46 UTC)
8
8
2,955 npm
-
Excalidraw MCP App Serverofficial
Design Tools Software Architecture
excalidraw
F
license
Not graded
quality
D
maintenance
Enables AI assistants to generate interactive Excalidraw diagrams with viewport camera control and fullscreen editing directly in the chat.
Updated 6 months ago (2026-03-24 12:27 UTC)
5,468
-
Smart-MCP
RAG Systems CI/CD & DevOps
IDRIMalek
F
license
Not graded
quality
D
maintenance
Generates complex draw.io diagrams (tables, kanbans, GANTT) using a local 9B LLM with RAG, featuring a real-time dashboard and CI/CD pipeline.
Updated 3 months ago (2026-06-24 20:27 UTC)
-
Excalidraw MCP App Server
Software Architecture Design Tools
vtmade
F
license
Not graded
quality
D
maintenance
Streams hand-drawn Excalidraw diagrams with smooth viewport camera control and interactive fullscreen editing, enabling diagram creation via natural language.
Updated 8 months ago (2026-02-06 10:36 UTC)
-

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 中显示

项目结构

制作更好图表的技巧

许可证

Available Tools

Output Schema

TDQS

Output Schema

TDQS

Output Schema

TDQS

Tool Schema Changelog

TDQS

Maintenance

Resources

Related MCP Connectors

Related MCP Servers

Excalidraw MCP Server

Excalidraw MCP App Serverofficial

Smart-MCP

Excalidraw MCP App Server

`generate_diagram` 参数