Mermaid MCP Server
Mermaid MCP Server
Model Context Protocol(MCP) 기반의 Mermaid 다이어그램 변환 서버로, AI 클라이언트에 강력한 다이어그램 생성 기능을 제공합니다
프로젝트 소개
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 설정
Cherry Studio를 엽니다
설정 → MCP Servers → 서버 추가로 이동합니다
매개변수 구성:
이름:
mermaid-mcp-server-png-pdf-jpg-svg설명:
Mermaid 다이어그램 생성 서비스유형:
STDIO명령어:
uvx매개변수:
mermaid-mcp-server-png-pdf-jpg-svg
저장 후 활성화합니다

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.pySSE 모드(네트워크 연결용)
uv run python main.py --sse설정 안내
환경 변수 설정
변수 이름 | 설명 | 기본값 |
| 서버 주소 |
|
| 서버 포트 |
|
| 로그 레벨 |
|
| Mermaid API 주소 |
|
| 요청 제한 시간(초) |
|
| 디버그 모드 |
|
| 개발 모드 |
|
사용 가능한 도구
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:
네트워크 연결 및 방화벽 설정 확인
mermaid.ink API 접근 가능 여부 확인
프록시 설정 확인
A:
validate_mermaid_syntax 도구로 문법 검사
Mermaid 공식 문서 참조
예시 리소스의 코드 사용
A:
다이어그램 내용 단순화
여러 개의 작은 다이어그램으로 분할
이미지 크기 매개변수 조정
A:
uv 패키지 매니저 설치:
curl -LsSf https://astral.sh/uv/install.sh | sh또는 pip로 전역 패키지 설치
PATH 환경 변수 확인
A:
서비스가 SSE 모드로 시작되었는지 확인
포트 8003이 점유 중인지 확인
URL 설정이 올바른지 확인
A:
이미지 크기 매개변수 증가
적절한 테마 선택
Mermaid 코드 구조 최적화
A:
네트워크 연결 속도 확인
REQUEST_TIMEOUT 환경 변수 증가
다이어그램 복잡도 단순화
A:
테마 이름 철자가 올바른지 확인
해당 테마 지원 여부 확인
다른 테마 이름 시도
A:
background_color 매개변수 사용
형식은 16진수 색상 코드(예: #FFFFFF)
일부 출력 형식만 지원
기술 교류 그룹
기술 교류 그룹에 참여하여 사용 경험과 피드백을 공유해 보세요:

작성자 연락처
위챗: laohaibao2025
이메일: 75271002@qq.com

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

Star History
프로젝트가 마음에 드신다면 Star ⭐를 눌러주세요
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를 환영합니다!
이 저장소를 Fork합니다
기능 브랜치를 생성합니다:
git checkout -b feature/amazing-feature변경 사항을 커밋합니다:
git commit -m 'Add amazing feature'브랜치에 푸시합니다:
git push origin feature/amazing-featurePull Request를 제출합니다
주의 사항
다이어그램 생성에 몇 초가 걸릴 수 있으니 잠시 기다려 주세요
서비스가 mermaid.ink 온라인 API에 의존하므로 네트워크 연결이 정상인지 확인하세요
생성된 이미지 데이터는 base64 형식으로 반환됩니다
복잡한 다이어그램은 더 긴 생성 시간이 필요할 수 있습니다
Mermaid로 아름다운 다이어그램을 만들어 보세요! 🎨✨
Available Tools
3 toolsconvert_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: 图像高度(像素,可选)
返回:
包含转换后图像数据和元数据的字典
| Name | Required | Description | Default |
|---|---|---|---|
| mermaid_code | Yes | ||
| output_format | No | png | |
| theme | No | default | |
| background_color | No | ||
| width | No | ||
| height | No |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden. It mentions the tool converts code to images and returns a dictionary with data and metadata, but lacks details on error handling, performance (e.g., rate limits), authentication needs, or side effects. This is inadequate for a mutation tool with zero annotation coverage.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded: the first sentence states the core purpose, followed by a structured list of parameters and return value. Every sentence earns its place with no redundant information, making it efficient and well-organized.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's complexity (6 parameters, mutation operation) and no annotations, the description does well by detailing all parameters and noting the return structure. However, it lacks behavioral context like error cases or limitations. The presence of an output schema mitigates some gaps, but more completeness is needed for a mutation tool.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It provides detailed semantics for all 6 parameters beyond the schema, including explanations of mermaid_code, output_format options, theme options, background_color syntax, and optional width/height. This adds significant value over the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('将 Mermaid 图表代码转换为多种格式的图像') with the resource (Mermaid chart code) and distinguishes from siblings by focusing on conversion rather than validation or option retrieval. It explicitly lists the output formats, making the purpose unambiguous.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying what the tool does, but does not explicitly state when to use it versus alternatives like validate_mermaid_syntax or get_supported_options. No guidance on prerequisites or exclusions is provided, leaving usage context partially inferred.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_supported_optionsA
获取转换器支持的选项,如图表主题和输出格式。
返回:
一个包含支持的主题和格式列表的字典。
| Name | Required | Description | Default |
|---|---|---|---|
No parameters | |||
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It discloses that the tool returns a dictionary with lists of supported themes and formats, which adds behavioral context beyond the input schema (which has no parameters). However, it doesn't cover other traits like performance, error handling, or authentication needs, leaving gaps in transparency for a tool with no annotation support.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is highly concise and well-structured: two sentences that directly state the purpose and return value, with no wasted words. It's front-loaded with the core function, and every sentence adds essential information, making it efficient for an agent to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (0 parameters, no annotations, but with an output schema), the description is reasonably complete. It explains what the tool does and the return format, which complements the output schema. However, it lacks usage context and some behavioral details, preventing a perfect score despite the structured support.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The tool has 0 parameters, and the input schema description coverage is 100% (with an empty schema). The description doesn't need to add parameter semantics, so it appropriately focuses on the return value. Since there are no parameters to document, a baseline score of 4 is justified, as the description doesn't introduce confusion or redundancy.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: '获取转换器支持的选项,如图表主题和输出格式' (Get converter-supported options, such as chart themes and output formats). It specifies both the action ('获取' - get) and the resource ('支持的选项' - supported options), with concrete examples. However, it doesn't explicitly differentiate from sibling tools like 'convert_mermaid_to_image' or 'validate_mermaid_syntax', which prevents a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools or suggest scenarios where this tool is appropriate (e.g., before conversion to check available options). Without any usage context or exclusions, it relies on implicit understanding, which is insufficient for clear agent decision-making.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
validate_mermaid_syntaxB
通过尝试简单转换来验证 Mermaid 图表语法。
参数:
mermaid_code: 要验证的 Mermaid 图表语法代码
返回:
包含验证结果的字典
| Name | Required | Description | Default |
|---|---|---|---|
| mermaid_code | Yes |
Output Schema
| Name | Required | Description |
|---|---|---|
| result | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions '尝试简单转换' (attempting simple conversion) as the validation method, which implies a read-only, non-destructive operation, but doesn't clarify error handling, performance implications, or what '简单转换' entails. For a tool with zero annotation coverage, this leaves significant gaps in understanding its behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is extremely concise and well-structured: a purpose statement followed by clear parameter and return sections in bullet-like format. Every sentence earns its place without redundancy, and it's front-loaded with the core functionality. The bilingual presentation (Chinese purpose, English labels) is efficient for clarity.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's low complexity (single parameter, no nested objects) and the presence of an output schema (which handles return values), the description is reasonably complete. It covers purpose, parameter semantics, and return type at a high level. However, it lacks usage guidelines and detailed behavioral context, which are minor gaps in this simple validation context.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description explicitly documents the single parameter 'mermaid_code' as '要验证的 Mermaid 图表语法代码' (Mermaid diagram syntax code to validate), adding meaning beyond the schema's basic title 'Mermaid Code'. However, with schema description coverage at 0%, it doesn't provide format details, constraints, or examples. The baseline is 3 since it compensates somewhat but not fully for the schema's lack of descriptions.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose as '验证 Mermaid 图表语法' (validate Mermaid diagram syntax) and specifies the method '通过尝试简单转换' (by attempting simple conversion). It distinguishes from sibling tools like 'convert_mermaid_to_image' by focusing on validation rather than conversion to image format. However, it doesn't explicitly differentiate from 'get_supported_options' which might relate to syntax options.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It doesn't mention sibling tools 'convert_mermaid_to_image' or 'get_supported_options', nor does it specify scenarios where validation is preferred over direct conversion or option checking. There's no indication of prerequisites or exclusions for usage.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
3 tool updates
- First observed
convert_mermaid_to_image - First observed
get_supported_options - First observed
validate_mermaid_syntax
TDQS
Scored across 3 tools
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.
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.
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.
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.
Maintenance
Related MCP Connectors
A Model Context Protocol server for Wix AI tools
A comprehensive Model Context Protocol (MCP) server that enables AI assistants to interact with yo…
Generate dynamic Mermaid diagrams and charts with AI assistance. Customize styles and export diagr…
Render, verify, describe, and safely edit Mermaid diagrams through MCP.
Related MCP Servers
- AlicenseBqualityCmaintenanceA Model Context Protocol (MCP) server that converts Mermaid diagrams to PNG images.1109 npm234MIT
- AlicenseBqualityCmaintenanceA Model Context Protocol server that validates and renders Mermaid diagrams.1183 npm57MIT
- AlicenseNot gradedqualityNot gradedmaintenanceA server that implements the Model Context Protocol (MCP), providing an interface for LLM applications to generate mermaid.js visualizations and diagrams.MIT
- FlicenseNot gradedqualityDmaintenanceA Model Context Protocol server that converts SVG code to PNG images, offering two conversion methods (CairoSVG and Inkscape) with support for custom working directories.3-