MCP-сервер Claude Mermaid

MCP-сервер для отрисовки диаграмм Mermaid в Claude Code с функцией живой перезагрузки (live reload) и встроенным навыком для получения экспертных рекомендаций.

Автоматически отображает диаграммы в вашем браузере с обновлениями в реальном времени по мере их редактирования. Идеально подходит для итеративной разработки диаграмм и рабочих процессов документирования.

✨ Функции

• 🔄 Живая перезагрузка — диаграммы автоматически обновляются в браузере по мере редактирования

• 🎨 Несколько форматов сохранения — экспорт в SVG, PNG или PDF

• 🌈 Темы — выбор между стандартной, лесной (forest), темной или нейтральной темами

• 📐 Настраиваемость — управление размерами, масштабом и цветами фона

• 🪄 Интерактивный предпросмотр — панорамирование диаграмм перетаскиванием, масштабирование элементами управления браузера, сброс позиции одним кликом

• ⬇️ Экспорт из браузера — скачивание диаграмм в формате SVG или PNG прямо из окна предпросмотра

• 🗂️ Несколько предпросмотров — используйте preview_id для одновременной работы с несколькими диаграммами

• 💾 Постоянные рабочие файлы — живые превью сохраняются в ~/.config/claude-mermaid/live

• 🤖 Встроенный навык — включает навык Claude с лучшими практиками и экспертными рекомендациями по созданию диаграмм

Related MCP server: mcp-mermaid-validator

Архитектура

🚀 Быстрый старт

1. Установка

Установка плагина (рекомендуется)

В Claude Code добавьте маркетплейс и установите плагин:

/plugin marketplace add veelenga/claude-mermaid
/plugin install claude-mermaid@claude-mermaid

Затем перезапустите Claude Code, чтобы активировать плагин.

Из npm:

npm install -g claude-mermaid

Из исходного кода:

git clone https://github.com/veelenga/claude-mermaid.git
cd claude-mermaid
npm install && npm run build && npm install -g .

2. Проверка установки

Установка плагина: MCP-сервер настраивается автоматически. Просто проверьте:

/mcp

Вы должны увидеть mermaid в списке MCP-серверов.

Установка через npm: Настройте MCP-сервер вручную:

claude mcp add --scope user mermaid claude-mermaid

Затем проверьте:

claude mcp list

Вы должны увидеть mermaid: claude-mermaid - ✓ Connected

🔌 Другие конфигурации MCP-клиентов

Хотя этот сервер оптимизирован для Claude Code, он может работать с любым MCP-совместимым клиентом. Вот как настроить его для других популярных инструментов:

Добавьте в файл настроек MCP Codex (~/.codex/mcp_settings.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Или настройте через CLI Codex:

codex mcp add mermaid claude-mermaid

Добавьте в файл конфигурации MCP Cursor (.cursor/mcp.json или настройки):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Или используйте интерфейс настроек Cursor:

1. Откройте настройки Cursor (Cmd/Ctrl + ,)

2. Перейдите к MCP Servers

3. Добавьте новый сервер с командой: claude-mermaid

Если вы используете расширение Cline для VSCode:

1. Откройте настройки VSCode (Cmd/Ctrl + ,)

2. Найдите "Cline MCP"

3. Добавьте в JSON настроек MCP:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Добавьте в файл конфигурации MCP Windsurf:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Расположение конфигурации зависит от платформы:

• macOS: ~/Library/Application Support/Windsurf/mcp.json

• Linux: ~/.config/windsurf/mcp.json

• Windows: %APPDATA%\Windsurf\mcp.json

Добавьте в файл конфигурации MCP Gemini CLI (~/.gemini/mcp.json):

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Или используйте Gemini CLI для настройки:

gemini config mcp add mermaid --command claude-mermaid

Для любого MCP-совместимого клиента используйте стандартную конфигурацию:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid"
    }
  }
}

Команда claude-mermaid должна быть доступна в вашем PATH после установки.

Примечание: Некоторым клиентам может потребоваться полный путь к исполняемому файлу:

• Найдите путь: which claude-mermaid (Unix/macOS) или where claude-mermaid (Windows)

• Используйте абсолютный путь в конфигурации: "command": "/path/to/claude-mermaid"

💡 Использование

Просто попросите Claude Code создать диаграммы Mermaid естественным образом. При установке в качестве плагина встроенный навык mermaid-diagrams предоставляет экспертные рекомендации, лучшие практики и автоматическое управление рабочим процессом.

Базовые примеры

"Create a Mermaid diagram showing the user authentication flow"
"Draw a sequence diagram for the payment process"
"Generate a flowchart for the deployment pipeline"

Продвинутые примеры

С пользовательским форматированием:

"Create a dark theme architecture diagram with transparent background"
"Generate a forest theme flowchart and save to ./docs/flow.svg"

С указанием формата вывода:

"Create an ER diagram and save as PDF to ./docs/schema.pdf"
"Save the flowchart as PNG to ./docs/flow.png"

Примечание: Браузер всегда показывает SVG для живого предпросмотра, в то время как сохранение происходит в выбранный вами формат.

Итеративное уточнение:

"Create a class diagram for the User module"
// Browser opens with live preview
"Add the Address and Order classes with relationships"
// Diagram updates automatically in browser!

Полный пример

"Create a flowchart and save to ./docs/auth-flow.svg:

graph LR
    A[User Login] --> B{Valid Credentials?}
    B -->|Yes| C[Access Granted]
    B -->|No| D[Access Denied]
    C --> E[Dashboard]
    D --> F[Try Again]

    style A fill:#e1f5ff
    style C fill:#d4edda
    style D fill:#f8d7da
"

Диаграмма будет сохранена в ./docs/auth-flow.svg и открыта в вашем браузере с включенной живой перезагрузкой.

🔧 Инструменты и параметры

MCP-сервер предоставляет два инструмента:

1. mermaid_preview — отрисовка и открытие живого предпросмотра

• diagram (строка, обязательно) — код диаграммы Mermaid

• preview_id (строка, обязательно) — идентификатор для этой сессии предпросмотра. Используйте разные ID для нескольких одновременных диаграмм (например, architecture, flow).

• format (строка, по умолчанию svg) — один из svg, png, pdf. Живой предпросмотр доступен только для svg.

• theme (строка, по умолчанию default) — один из default, forest, dark, neutral.

• background (строка, по умолчанию white) — цвет фона. Примеры: transparent, white, #F0F0F0.

• width (число, по умолчанию 800) — ширина диаграммы в пикселях.

• height (число, по умолчанию 600) — высота диаграммы в пикселях.

• scale (число, по умолчанию 2) — коэффициент масштабирования для более высокого качества вывода.

2. mermaid_save — сохранение текущей живой диаграммы по пути

• save_path (строка, обязательно) — путь назначения (например, ./docs/diagram.svg).

• preview_id (строка, обязательно) — должен совпадать с preview_id, использованным в mermaid_preview.

• format (строка, по умолчанию svg) — один из svg, png, pdf. Если рабочий файл для этого формата еще не существует, он отрисовывается по запросу перед сохранением.

🎯 Как работает живая перезагрузка

1. Первая отрисовка: Открывает диаграмму в браузере по адресу http://localhost:3737/{preview_id}

2. Внесение изменений: Редактируйте диаграмму через Claude Code

3. Автообновление: Браузер обнаруживает изменения через WebSocket и перезагружается

4. Индикатор статуса: Зеленая точка = подключено, Красная точка = переподключение

Живой сервер использует порты 3737-3747 и автоматически находит доступный порт.

Элементы управления живым предпросмотром

• Панорамирование: Нажмите и перетащите диаграмму, чтобы переместить ее

• Масштабирование: Используйте масштабирование браузера (Ctrl/Cmd + +/- или щипок на тачпаде)

• Сброс позиции: Нажмите кнопку ⊙ в строке состояния, чтобы отцентрировать диаграмму

• Экспорт: Нажмите кнопку ⬇ для скачивания в формате SVG или PNG

Примечания

• Живой предпросмотр доступен только для формата svg; PNG/PDF отрисовываются без живой перезагрузки.

• Для диаграмм последовательности (sequence diagrams) Mermaid не поддерживает директивы style внутри sequenceDiagram.

🖥️ Автономный сервер

Вы можете запустить сервер предпросмотра без AI-агента, используя флаг --serve:

claude-mermaid --serve

Это откроет галерею диаграмм в вашем браузере со всеми ранее отрисованными диаграммами. Полезно для просмотра и экспорта диаграмм вне сессии Claude Code.

🛠️ Разработка

# Install dependencies
npm install

# Build the project
npm run build

# Run tests
npm test

# Watch mode for development
npm run dev

# Start the MCP server directly
npm start

📝 Устранение неполадок

Ошибка: Cannot find package 'puppeteer':

Это редкая проблема, зависящая от окружения. Попробуйте следующие решения:

1. Установите claude-mermaid глобально:

npm install -g claude-mermaid

2. Переустановите плагин в Claude Code:

/plugin uninstall claude-mermaid
/plugin install claude-mermaid@claude-mermaid

Сервер не подключается:

# Check if server is installed
claude-mermaid -v

# Reinstall if needed
npm install -g claude-mermaid

# Verify MCP configuration
claude mcp list

Ошибка отказа в доступе (Permission denied):

# Make sure the binary is executable
chmod +x $(which claude-mermaid)

Порт уже используется:

• Сервер использует порты 3737-3747

• Он автоматически найдет доступный порт

• Проверьте, не использует ли другой процесс эти порты: lsof -i :3737-3747

Диаграммы не отрисовываются или живая перезагрузка не работает:

Сервер ведет логи в ~/.config/claude-mermaid/logs/:

• mcp.log - запросы инструментов и отрисовка диаграмм

• web.log - HTTP/WebSocket соединения и живая перезагрузка

Включите отладочное логирование в вашей конфигурации MCP:

{
  "mcpServers": {
    "mermaid": {
      "command": "claude-mermaid",
      "env": {
        "CLAUDE_MERMAID_LOG_LEVEL": "DEBUG"
      }
    }
  }
}

Затем проверьте логи:

# View MCP operations
tail -f ~/.config/claude-mermaid/logs/mcp.log

# View WebSocket connections
tail -f ~/.config/claude-mermaid/logs/web.log

Доступные уровни логирования: DEBUG, INFO (по умолчанию), WARN, ERROR, OFF

🤝 Участие в разработке

Вклад приветствуется! Пожалуйста, не стесняйтесь отправлять Pull Request.

📄 Лицензия

MIT - подробности см. в файле LICENSE

🔗 Ссылки

• Репозиторий GitHub

• Пакет npm

• Документация Claude Code

• Документация Mermaid

👀 Смотрите также

Если вам нравится этот проект, вас также может заинтересовать

• preview-skills — навыки предпросмотра для визуализации файлов в браузере (markdown, csv, json, mermaid и другие)

Хостинговое развертывание

Хостинговое развертывание доступно на Fronteir AI.