Skip to main content
Glama
wwwzhouhui

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 四种精美主题

  • 自定义选项: 支持背景颜色、图像尺寸等参数自定义

  • 语法验证: 提供实时的 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+

Web 框架(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 包管理器(推荐)

安装依赖

方式一:使用 uv 安装(推荐)

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

# 安装依赖
uv sync

方式二:使用 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

常见问题

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. 格式为十六进制颜色代码(如 #FFFFFF)

  3. 仅支持部分输出格式


技术交流群

欢迎加入技术交流群,分享你的使用心得和反馈建议:

技术交流群


作者联系

微信二维码


打赏

如果这个项目对你有帮助,欢迎请我喝杯咖啡 ☕

微信支付

微信支付


Star History

如果觉得项目不错,欢迎点个 Star ⭐

Star History Chart


License

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


注意事项

  • 图表生成可能需要几秒钟时间,请耐心等待

  • 确保网络连接正常,服务依赖 mermaid.ink 在线 API

  • 生成的图像数据以 base64 格式返回

  • 复杂图表可能需要更长的生成时间


Enjoy creating beautiful diagrams with 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: 图像高度(像素,可选)

返回:
    包含转换后图像数据和元数据的字典
ParametersJSON Schema
NameRequiredDescriptionDefault
mermaid_codeYes
output_formatNopng
themeNodefault
background_colorNo
widthNo
heightNo

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.9/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters5/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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
获取转换器支持的选项,如图表主题和输出格式。

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

No parameters

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

A3.5/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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 图表语法代码

返回:
    包含验证结果的字典
ParametersJSON Schema
NameRequiredDescriptionDefault
mermaid_codeYes

Output Schema

ParametersJSON Schema
NameRequiredDescription
resultYes

TDQS

B3.2/5.0
Behavior2/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters3/5

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.

Purpose4/5

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.

Usage Guidelines2/5

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.

  1. 3 tool updates
    • First observedconvert_mermaid_to_image
    • First observedget_supported_options
    • First observedvalidate_mermaid_syntax

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.

Maintenance

ActivityActive
ResponsivenessNo issues

Related MCP Connectors

Related MCP Servers