Skip to main content
Glama
Mermaid MCP Server

Mermaid MCP Server

by wwwzhouhui

Mermaid MCP Server

Model Context Protocol(MCP) 기반의 Mermaid 다이어그램 변환 서버로, AI 클라이언트에 강력한 다이어그램 생성 기능을 제공합니다

License Python MCP UV


프로젝트 소개

Mermaid MCP Server는 Model Context Protocol(MCP) 기반의 전문 Mermaid 다이어그램 변환 서버로, AI 클라이언트에 강력한 다이어그램 생성 기능을 제공합니다. 이 프로젝트는 Mermaid 다이어그램 코드를 PNG, JPG, SVG, PDF 등 다양한 형식의 이미지 파일로 변환하여, MCP 프로토콜을 지원하는 다양한 AI 클라이언트에서 고품질 다이어그램을 쉽게 생성할 수 있게 해줍니다.

핵심 기능

  • 다중 형식 출력: PNG, JPG, SVG, PDF 등 다양한 이미지 형식 지원

  • 테마 커스터마이징: default, dark, neutral, forest 4가지 세련된 테마 내장

  • 사용자 정의 옵션: 배경 색상, 이미지 크기 등 매개변수 사용자 정의 지원

  • 문법 검증: 실시간 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, 선택): 배경 색상, 16진수 코드

  • 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

자주 묻는 질문

A:

  1. 네트워크 연결 및 방화벽 설정 확인

  2. mermaid.ink API 접근 가능 여부 확인

  3. 프록시 설정 확인

A:

  1. validate_mermaid_syntax 도구로 문법 검사

  2. Mermaid 공식 문서 참조

  3. 예시 리소스의 코드 사용

A:

  1. 다이어그램 내용 단순화

  2. 여러 개의 작은 다이어그램으로 분할

  3. 이미지 크기 매개변수 조정

A:

  1. uv 패키지 매니저 설치: curl -LsSf https://astral.sh/uv/install.sh | sh

  2. 또는 pip로 전역 패키지 설치

  3. PATH 환경 변수 확인

A:

  1. 서비스가 SSE 모드로 시작되었는지 확인

  2. 포트 8003이 점유 중인지 확인

  3. URL 설정이 올바른지 확인

A:

  1. 이미지 크기 매개변수 증가

  2. 적절한 테마 선택

  3. Mermaid 코드 구조 최적화

A:

  1. 네트워크 연결 속도 확인

  2. REQUEST_TIMEOUT 환경 변수 증가

  3. 다이어그램 복잡도 단순화

A:

  1. 테마 이름 철자가 올바른지 확인

  2. 해당 테마 지원 여부 확인

  3. 다른 테마 이름 시도

A:

  1. background_color 매개변수 사용

  2. 형식은 16진수 색상 코드(예: #FFFFFF)

  3. 일부 출력 형식만 지원


기술 교류 그룹

기술 교류 그룹에 참여하여 사용 경험과 피드백을 공유해 보세요:

기술 교류 그룹


작성자 연락처

위챗 QR 코드


후원

이 프로젝트가 도움이 되셨다면 커피 한 잔 ☕ 사주시면 감사하겠습니다

위챗 페이

위챗 페이


Star History

프로젝트가 마음에 드신다면 Star ⭐를 눌러주세요

Star History Chart


License

MIT License


업데이트 로그

v0.1.0 (현재 버전)

  • ✅ 초기 버전 출시

  • ✅ PNG, JPG, SVG, PDF 다중 형식 출력 지원

  • ✅ 4가지 테마 스타일 통합(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를 제출합니다


주의 사항

  • 다이어그램 생성에 몇 초가 걸릴 수 있으니 잠시 기다려 주세요

  • 서비스가 mermaid.ink 온라인 API에 의존하므로 네트워크 연결이 정상인지 확인하세요

  • 생성된 이미지 데이터는 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