Skip to main content
Glama
enjaruzh
jeel00dev

Excalidraw MCP Server

by jeel00dev
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Local

Excalidraw MCP サーバー

自然言語から美しい Excalidraw ダイアグラムを生成します。クラウド API は不要で、完全にローカルで動作します。

「eコマースアプリのマイクロサービスアーキテクチャを描いて」のように指示すると、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 では、GPU アクセラレーションのために -DLLAMA_METAL=ON を追加してください。

ステップ 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/ に保存されます。

  1. excalidraw.com またはローカルインスタンスを開く

  2. フォルダアイコン (左上) をクリック → 開く

  3. .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 を明示的に指定する (例: "freeform" ではなく "flowchart")

  • より大きなモデル (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

より良いダイアグラムのためのヒント

  1. 具体的に記述する: 「ログインフロー」よりも「メール/パスワード、JWT トークン、セッションストレージを使用したログインフロー」の方が優れています

  2. 要素に名前を付ける: 「矢印でつながれた A、B、C というラベルのボックス」のように指定すると、Excalidraw がその命名に従います

  3. 色を指定する: 「サービスには青、データベースには黄色を使用」のように指定します

  4. 焦点を絞る: すべてを表示しようとするよりも、1 つのダイアグラムにつき 1 つの論理的概念に絞る方がうまくいきます

  5. 自由に再生成する: 最初の結果が完璧でない場合は、別のファイル名で再度依頼してください。すぐに生成されます

ライセンス

MIT

Available Tools

3 tools
check_llm_statusA

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

ParametersJSON Schema
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault
descriptionYes
diagram_typeNoflowchart
filenameNodiagram

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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
NameRequiredDescriptionDefault

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

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.

  1. 3 tool updatesv0.1.0
    • 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 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

Related MCP Connectors

Related MCP Servers