Mermaid MCP 서버

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

👁 License
👁 Python
👁 MCP
👁 UV

프로젝트 소개

Mermaid MCP 서버는 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

기능 목록

기술 아키텍처

통신 아키텍처

┌─────────────────────────────────────────────────────────────────────────────────┐
│ 通信架构图 │
├─────────────────────────────────────────────────────────────────────────────────┤
│ │
│ ┌──────────────────┐ ┌─────────────────────────┐ ┌─────────────┐ │
│ │ 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, 선택): 배경색, 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

자주 묻는 질문 (FAQ)

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. 일부 출력 형식만 지원

기술 교류 그룹

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

👁 微信图片_20260501235133_120_6

작성자 연락처

• 위챗: laohaibao2025

• 이메일: 75271002@qq.com

👁 위챗 QR 코드

후원

이 프로젝트가 도움이 되었다면 커피 한 잔 사주세요 ☕

위챗 페이

👁 위챗 페이

Star History

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

👁 Star History Chart

라이선스

MIT 라이선스

업데이트 로그

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로 아름다운 다이어그램을 만들어 보세요! 🎨✨

Maintenance

Resources

• GitHub Repository
Need Help?
• Reddit Discussion
Related Servers

Tools

• convert_mermaid_to_imageA
• get_supported_optionsA
• validate_mermaid_syntaxB