Skip to main content
Glama
Mermaid MCP Server

Mermaid MCP Server

by wwwzhouhui

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

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

Название функции

Описание функции

Технологический стек

Статус

Преобразование диаграмм

Код Mermaid в изображение

mermaid.ink API

✅ Стабильно

Многоформатный вывод

PNG/JPG/SVG/PDF

requests + base64

✅ Стабильно

Настройка тем

4 встроенные темы

mermaid.ink

✅ Стабильно

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

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

mermaid-cli

✅ Стабильно

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

Богатые примеры диаграмм

Статические ресурсы

✅ Стабильно

Обработка ошибок

Понятные сообщения об ошибках

Обработка исключений Python

✅ Стабильно

Протокол MCP

Model Context Protocol

mcp[cli]

✅ Стабильно

Режим SSE

Server-Sent Events

FastAPI + Uvicorn

✅ Стабильно


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

Технология

Версия

Назначение

Python

3.12+

Основной язык разработки

MCP

1.9+

Model Context Protocol

FastAPI

0.104+

Веб-фреймворк (режим SSE)

Uvicorn

0.24+

ASGI-сервер

requests

2.31+

HTTP-клиент

uv

latest

Менеджер пакетов Python

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

┌─────────────────────────────────────────────────────────────────────────────────┐
│                            通信架构图                                            │
├─────────────────────────────────────────────────────────────────────────────────┤
│                                                                                 │
│   ┌──────────────────┐       ┌─────────────────────────┐       ┌─────────────┐ │
│   │  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

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

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

Имя переменной

Описание

Значение по умолчанию

HOST

Адрес сервера

0.0.0.0

PORT

Порт сервера

8003

LOG_LEVEL

Уровень журналирования

INFO

MERMAID_API_BASE_URL

Адрес Mermaid API

https://mermaid.ink

REQUEST_TIMEOUT

Время ожидания запроса (секунды)

30

DEBUG

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

false

DEVELOPMENT_MODE

Режим разработки

false


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

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. Убедитесь, что mermaid.ink API доступен

  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. Поддерживается только для некоторых форматов вывода


Техническое сообщество

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

Техническое сообщество


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

QR-код WeChat


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

Если этот проект оказался для вас полезным, вы можете угостить меня чашечкой кофе ☕

WeChat Pay

WeChat Pay


Star History

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

Star History Chart


Лицензия

Лицензия MIT


Журнал обновлений

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

  • ✅ Выпущена начальная версия

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

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

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

  • ✅ Поддержка двух режимов связи: STDIO и SSE

v0.0.3 (2025-07-21)

  • ✅ Выпущена начальная версия

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

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

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


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

Приглашаем отправлять Issue и Pull Request для улучшения этого проекта!

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

  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! 🎨✨

Available Tools

3 tools
convert_mermaid_to_imageA
将 Mermaid 图表代码转换为多种格式的图像(PNG、JPG、PDF、SVG)。

参数:
    mermaid_code: 要转换的 Mermaid 图表语法代码
    output_format: 输出格式 - png、jpg、svg 或 pdf(默认:png)
    theme: 视觉主题 - default、dark、neutral 或 forest(默认:default)
    background_color: 背景颜色,十六进制代码(如 FF0000)或带 ! 前缀的命名颜色(如 !white)
    width: 图像宽度(像素,可选)
    height: 图像高度(像素,可选)

返回:
    包含转换后图像数据和元数据的字典

Inputs: mermaid_code (required), output_format, theme, background_color, +2 more. Returns: result

get_supported_optionsA
获取转换器支持的选项,如图表主题和输出格式。

返回:
    一个包含支持的主题和格式列表的字典。

Inputs: no named parameters. Returns: result

validate_mermaid_syntaxB
通过尝试简单转换来验证 Mermaid 图表语法。

参数:
    mermaid_code: 要验证的 Mermaid 图表语法代码

返回:
    包含验证结果的字典

Inputs: mermaid_code (required). Returns: result

Tool Schema Changelog

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

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 3 tools

    Disambiguation5/5

    Each tool has a clearly distinct purpose: convert_mermaid_to_image handles the core conversion functionality, get_supported_options provides metadata about available options, and validate_mermaid_syntax performs syntax validation. There is no overlap or ambiguity between these three functions.

    Naming Consistency5/5

    All tools follow a consistent snake_case naming pattern with clear verb-action structure: convert_mermaid_to_image, get_supported_options, and validate_mermaid_syntax. The naming is predictable and follows the same convention throughout.

    Tool Count4/5

    Three tools is a reasonable number for a Mermaid diagram conversion server, though it feels slightly minimal. The tools cover the essential operations (convert, validate, get options), but additional utilities like listing available themes or handling diagram editing might enhance completeness.

    Completeness4/5

    The tool set covers the core Mermaid conversion workflow well: conversion, syntax validation, and option discovery. Minor gaps include operations like batch conversion, diagram editing utilities, or theme management, but agents can work effectively with the provided tools for most use cases.

    Related MCP Connectors

    Related MCP Servers