mermaid_mcp_server

Mermaid MCP Server 提供基于 MCP 的接口来将 Mermaid 图表代码转换为多格式图像（PNG、JPG、SVG、PDF），并支持主题自定义、语法验证以及实时的错误提示。服务器通过 STDIO 或 SSE 与 AI 客户端进行通信，利用 Mermaid 转换管线调用 Mermaid 的渲染能力并通过 mermaid.ink 等服务生成目标格式的图像。可用工具包括 convert_mermaid_to_image（将 Mermaid 代码转换为图片，支持自定义格式、主题与尺寸）、validate_mermaid_syntax（实时验证 Mermaid 语法）以及 get_supported_options（获取可用主题和格式）。通过 MCP 标准数据结构进行请求与响应，便于在不同客户端（Cursor、Cherry Studio、Claude Desktop、Continue.dev 等）之间互操作。

要使用该服务，请将 MCP 服务器配置加入客户端的 mcp.json（STDIO 模式）或相应的 SSE 配置。例如，STDIO 模式下的命令会以 uvx 启动并传递服务器标识，确保 Mermaid API 基本可访问并能返回所需的图像格式。SSE 模式则通过 Web 套接字事件保持持续连接，适合网络化工作流。

先决条件:

• Python 3.12+ 以及 uv 包管理器（推荐）
• 具备网络访问能力以调用 Mermaid API（mermaid.ink）

安装步骤:

1. 克隆仓库并进入项目目录

git clone https://github.com/wwwzhouhui/mermaid_mcp_server.git
cd mermaid_mcp_server

2. 安装依赖（使用 uv 同步安装）

uv sync

或按常规 Python 依赖安装方式

pip install -r requirements.txt

3)（可选）复制环境变量模板并配置

cp .env.example .env

4. 通过 MCP 客户端按以下方式启动 STDIO 模式（推荐）

uv run python main.py

5. 若需要 SSE 模式，使用以下启动命令

uv run python main.py --sse

若你直接使用 npm/Node 生态，请确保已切换到 Python 版本的实现路径，并以 uvx 方式注册服务器。

注: 具体配置路径可能因客户端而异，请参考对应客户端的 MCP 配置文档将 mermaid-mcp-server-png-pdf-jpg-svg 条目添加到 mcpServers。

环境变量提示:

• HOST: 服务器地址，默认为 0.0.0.0
• PORT: 服务器端口，默认为 8003
• MERMAID_API_BASE_URL: 指定 Mermaid 渲染 API 基地址，默认 https://mermaid.ink
• REQUEST_TIMEOUT: 请求超时（秒），默认 30
• DEBUG: 调试模式，默认 false
• DEVELOPMENT_MODE: 开发模式，默认 false

常见问题要点:

• 如何解决 uvx 命令找不到的问题：确保已安装 uv 包管理器，或在系统 PATH 中可执行 uvx，必要时重新安装 uv 包管理器。
• SSE 模式连接问题：检查服务是否以 SSE 启动、端口占用情况以及 URL 是否正确配置。
• 生成的图像质量问题：增加图像尺寸参数、选择合适主题、简化 Mermaid 代码结构。
• 转换超时：增大 REQUEST_TIMEOUT，优化网络条件或简化图表。
• 主题不生效：确认主题参数与 Mermaid 主题名称匹配，以及使用的输出格式支持该主题。

调试与日志:

• 可以通过设置 LOG_LEVEL=DEBUG 来获得详细日志输出。