MCP-сервер Excalidraw

Генерируйте красивые диаграммы Excalidraw на основе естественного языка — полностью локально, без необходимости в облачном API.

Вы описываете, что хотите («нарисуй архитектуру микросервисов для приложения электронной коммерции»), а MCP-сервер обращается к вашей локальной LLM llama.cpp для создания корректного файла .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

Предварительные требования

Настройка

Шаг 1 — Сборка llama.cpp

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

На macOS с Apple Silicon добавьте -DLLAMA_METAL=ON для ускорения на GPU.

Шаг 2 — Загрузка модели GGUF

Рекомендуемые модели (лучшее качество вывода JSON):

# 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-сервера попросите своего ИИ-клиента:

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

Открытие созданной диаграммы

Диаграммы сохраняются в ~/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 looks wrong / missing elements"

• Будьте более конкретны в описании

• Явно укажите 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

Советы для создания лучших диаграмм

1. Будьте конкретны: "поток входа с email/паролем, JWT-токеном и хранилищем сессий" лучше, чем просто "поток входа"

2. Именуйте элементы: "блоки с метками A, B, C, соединенные стрелками" — Excalidraw следует вашим именам

3. Указывайте цвета: "используй синий для сервисов, желтый для баз данных"

4. Сосредоточьтесь: одна логическая концепция на диаграмму работает лучше, чем попытка показать всё сразу

5. Пересоздавайте свободно: если первый результат не идеален, попросите снова с другим именем файла — это происходит мгновенно

Лицензия

MIT