Mermaid MCP Server

Сервер для преобразования диаграмм Mermaid на базе Model Context Protocol (MCP), предоставляющий AI-клиентам мощные возможности генерации диаграмм

👁 License
👁 Python
👁 MCP
👁 UV

О проекте

Mermaid MCP Server — это профессиональный сервер для преобразования диаграмм Mermaid на базе Model Context Protocol (MCP), предоставляющий AI-клиентам мощные возможности генерации диаграмм. Проект позволяет преобразовывать код диаграмм Mermaid в различные форматы изображений (PNG, JPG, SVG, PDF), позволяя пользователям легко создавать высококачественные диаграммы в любых AI-клиентах, поддерживающих протокол MCP.

Основные характеристики

• Многоформатный вывод: поддержка форматов PNG, JPG, SVG, PDF и других

• Настройка тем: встроенные темы: default, dark, neutral, forest

• Параметры настройки: поддержка настройки цвета фона, размеров изображения и других параметров

• Проверка синтаксиса: функция проверки синтаксиса Mermaid в реальном времени

• Примеры ресурсов: встроенные примеры кода для различных типов диаграмм

• Обработка ошибок: надежный механизм обработки ошибок и понятные сообщения об ошибках

• Двойной режим STDIO/SSE: поддержка режимов связи STDIO и SSE

• Управление пакетами uv: использование сверхбыстрого менеджера пакетов uv

Related MCP server: mcp-mermaid-validator

Список функций

Техническая архитектура

Архитектура связи

┌─────────────────────────────────────────────────────────────────────────────────┐
│ 通信架构图 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌─────────────────────────┐ ┌─────────────┐ │
│ │ AI 客户端 │ ◄────► │ Mermaid MCP Server │ ◄────► │ Mermaid API │ │
│ │ (Cursor/Claude) │ │ STDIO/SSE │ │ mermaid.ink│ │
│ └──────────────────┘ └─────────────────────────┘ └─────────────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ AI 对话界面 MCP 协议通信 图表渲染转换 │
│ 生成图表请求 双向数据传输 返回图像数据 │
│ │
└─────────────────────────────────────────────────────────────────────────────────┘

Инструкция по установке

Системные требования

• Python 3.12+

• Менеджер пакетов uv (рекомендуется)

Установка зависимостей

Способ 1: Установка через uv (рекомендуется)

# 克隆仓库
git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server

# 安装依赖
uv sync

Способ 2: Установка через pip

pip install -r requirements.txt

Инструкция по использованию

Настройка клиента

Настройка Cursor

Добавьте следующую конфигурацию в файл ~/.cursor/mcp.json:

Режим STDIO (рекомендуется):

{
 "mcpServers": {
 "mermaid-mcp-server-png-pdf-jpg-svg": {
 "command": "uvx",
 "args": [
 "mermaid-mcp-server-png-pdf-jpg-svg"
 ]
 }
 }
}

Режим SSE:

{
 "mcpServers": {
 "mermaid-mcp-server-png-pdf-jpg-svg": {
 "url": "http://127.0.0.1:8003/sse"
 }
 }
}

Настройка Cherry Studio

1. Откройте Cherry Studio

2. Перейдите в Настройки → MCP Servers → Добавить сервер

3. Настройте параметры:

   • Имя: mermaid-mcp-server-png-pdf-jpg-svg

   • Описание: Сервис генерации диаграмм Mermaid

   • Тип: STDIO

   • Команда: uvx

   • Аргументы: mermaid-mcp-server-png-pdf-jpg-svg

4. Нажмите «Сохранить» и активируйте

👁 Пример настройки Cherry Studio

Настройка Claude Desktop

Добавьте в файл claude_desktop_config.json:

{
 "mcpServers": {
 "mermaid-mcp-server-png-pdf-jpg-svg": {
 "command": "uvx",
 "args": [
 "mermaid-mcp-server-png-pdf-jpg-svg"
 ]
 }
 }
}

Настройка Continue.dev

Добавьте в файл config.json:

{
 "mcpServers": {
 "mermaid-mcp-server-png-pdf-jpg-svg": {
 "command": "uvx",
 "args": [
 "mermaid-mcp-server-png-pdf-jpg-svg"
 ]
 }
 }
}

Запуск службы

Режим STDIO (рекомендуется для настольных клиентов)

uv run python main.py

Режим SSE (для сетевого подключения)

uv run python main.py --sse

Описание конфигурации

Настройка переменных окружения

Доступные инструменты

1. convert_mermaid_to_image

Преобразует код диаграммы Mermaid в файл изображения различных форматов

Параметры:

• mermaid_code (string): Код диаграммы Mermaid

• output_format (string, опционально): Формат вывода, поддерживает png, jpg, svg, pdf, по умолчанию "png"

• theme (string, опционально): Стиль темы, поддерживает default, dark, neutral, forest, по умолчанию "default"

• background_color (string, опционально): Цвет фона, шестнадцатеричный код

• width (number, опционально): Ширина изображения (пиксели)

• height (number, опционально): Высота изображения (пиксели)

Поддерживаемые форматы вывода: PNG, JPG, SVG, PDF

2. validate_mermaid_syntax

Проверяет правильность синтаксиса кода диаграммы Mermaid

Параметры:

• mermaid_code (string): Код диаграммы Mermaid для проверки

Результат:

• valid (boolean): Пройдена ли проверка

• error_message (string): Сообщение об ошибке (если проверка не пройдена)

3. get_supported_options

Получает список опций, поддерживаемых конвертером

Результат:

• themes (array): Список поддерживаемых тем

• formats (array): Список поддерживаемых форматов

Поддерживаемые типы диаграмм

• Блок-схема (Flowchart): для представления процессов и алгоритмов

• Диаграмма последовательности (Sequence Diagram): для представления взаимодействия между объектами

• Диаграмма Ганта (Gantt Chart): для управления графиком проекта

• Круговая диаграмма (Pie Chart): для представления долей данных

• Git-граф (Git Graph): для представления истории коммитов Git

• Интеллект-карта (Mind Map): для представления структуры знаний

• Диаграмма классов (Class Diagram): для представления структуры классов

Примеры использования

Пример блок-схемы

请使用 convert_mermaid_to_image 工具生成一个流程图：
flowchart TD
 A[开始] --> B{判断条件}
 B -->|是 | C[执行动作 1]
 B -->|否 | D[执行动作 2]
 C --> E[结束]
 D --> E

Пример диаграммы последовательности

请使用 convert_mermaid_to_image 工具生成一个时序图，使用深色主题：
sequenceDiagram
 participant 用户
 participant 系统
 participant 数据库

 用户->>系统：登录请求
 系统->>数据库：验证用户
 数据库-->>系统：返回结果
 系统-->>用户：登录成功

Пример проверки синтаксиса

首先使用 validate_mermaid_syntax 验证语法，然后使用 convert_mermaid_to_image 生成图表

Примеры ресурсов

Получение примеров диаграмм

Примеры диаграмм различных типов можно получить через следующие URI ресурсов:

• mermaid://examples/flowchart - пример блок-схемы

• mermaid://examples/sequence - пример диаграммы последовательности

• mermaid://examples/gantt - пример диаграммы Ганта

• mermaid://examples/pie - пример круговой диаграммы

• mermaid://examples/gitgraph - пример Git-графа

• mermaid://examples/mindmap - пример интеллект-карты

• mermaid://examples/class - пример диаграммы классов

Структура проекта

mermaid_mcp_server/
├── mermaid_mcp_server/ # 核心模块
│ ├── __init__.py
│ └── main.py # 主程序入口
├── requirements.txt # 依赖列表（pip）
├── pyproject.toml # 项目配置（uv）
├── .env.example # 环境变量示例
├── README.md # 项目文档
└── .vscode/ # VSCode 配置
 └── settings.json

Руководство по разработке

Локальная разработка

# 克隆仓库
git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server

# 安装依赖
uv sync

# 配置环境变量
cp .env.example .env

# 启动服务（STDIO 模式）
uv run python main.py

# 启动服务（SSE 模式）
uv run python main.py --sse

Режим отладки

Включение подробного вывода логов:

export LOG_LEVEL=DEBUG
uv run python main.py

Часто задаваемые вопросы

О:

1. Проверьте сетевое подключение и настройки брандмауэра

2. Убедитесь, что API mermaid.ink доступен

3. Проверьте настройки прокси

О:

1. Используйте инструмент validate_mermaid_syntax для проверки синтаксиса

2. Обратитесь к официальной документации Mermaid

3. Используйте код из примеров ресурсов

О:

1. Упростите содержимое диаграммы

2. Разбейте на несколько небольших диаграмм

3. Настройте параметры размера изображения

О:

1. Установите менеджер пакетов uv: curl -LsSf https://astral.sh/uv/install.sh | sh

2. Или используйте глобальную установку пакета через pip

3. Проверьте переменную окружения PATH

О:

1. Убедитесь, что служба запущена в режиме SSE

2. Проверьте, не занят ли порт 8003

3. Убедитесь, что URL настроен правильно

О:

1. Увеличьте параметры размера изображения

2. Выберите подходящую тему

3. Оптимизируйте структуру кода Mermaid

О:

1. Проверьте скорость сетевого подключения

2. Увеличьте переменную окружения REQUEST_TIMEOUT

3. Упростите сложность диаграммы

О:

1. Убедитесь, что имя темы написано правильно

2. Проверьте, поддерживается ли эта тема

3. Попробуйте использовать другое имя темы

О:

1. Используйте параметр background_color

2. Формат — шестнадцатеричный код цвета (например, #FFFFFF)

3. Поддерживается только для некоторых форматов вывода

Группа технического общения

Приглашаем вас присоединиться к группе технического общения, чтобы поделиться своим опытом и предложениями:

👁 微信图片_20260501235133_120_6

Контакты автора

• WeChat: laohaibao2025

• Email: 75271002@qq.com

👁 QR-код WeChat

Поддержка проекта

Если этот проект помог вам, буду рад чашке кофе ☕

WeChat Pay

👁 WeChat Pay

История звезд

Если проект вам понравился, поставьте звезду ⭐

👁 Star History Chart

Лицензия

MIT License

Журнал изменений

v0.1.0 (текущая версия)

• ✅ Выпущен начальный релиз

• ✅ Поддержка многоформатного вывода (PNG, JPG, SVG, PDF)

• ✅ Интегрированы четыре стиля тем (default, dark, neutral, forest)

• ✅ Предоставлены функции проверки синтаксиса и примеры ресурсов

• ✅ Поддержка двойного режима связи STDIO и SSE

v0.0.3 (2025-07-21)

• ✅ Выпущен начальный релиз

• ✅ Поддержка преобразования диаграмм в несколько форматов

• ✅ Функция проверки синтаксиса

• ✅ Функция примеров ресурсов

Руководство по внесению вклада

Приветствуются Issue и Pull Request для улучшения проекта!

1. Сделайте Fork этого репозитория

2. Создайте ветку для функции: git checkout -b feature/amazing-feature

3. Зафиксируйте изменения: git commit -m 'Add amazing feature'

4. Отправьте изменения в ветку: git push origin feature/amazing-feature

5. Создайте Pull Request

Примечания

• Генерация диаграммы может занять несколько секунд, пожалуйста, подождите

• Убедитесь, что сетевое подключение в порядке, служба зависит от онлайн-API mermaid.ink

• Данные созданного изображения возвращаются в формате base64

• Сложные диаграммы могут потребовать больше времени для генерации

Наслаждайтесь созданием красивых диаграмм с Mermaid! 🎨✨

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• convert_mermaid_to_imageA
• get_supported_optionsA
• validate_mermaid_syntaxB