使用说明

mermaid mcp——一个mcp服务器，用于绘制任何项目的图表（本地/GitHub→ 美人鱼→ PNG)

Mermaid MCP服务器 是一个MCP服务器，帮助代理将大型代码库（本地文件夹或GitHub存储库）转换为 美人鱼图 并将其呈现为 PNG图像 通过 克罗基，能够快速、可靠地理解项目的结构和流程。

为什么选择此服务器

使用新代码库时，很容易在文件夹和文件之间浪费时间。此服务器为代理提供了一个干净的、基于工具的工作流发现, 读，以及 可视化 一个项目——不用猜测路径或发明结构。

主要特点

本地+GitHub资源：分析本地项目文件夹或远程存储库。
代理友好型管道: list_files → read_file → 生成美人鱼→ render_mermaid.
安全的本地访问边界：本地读取仅限于 PROJECT_ROOT.
可配置的限制：控制最大文件大小(MAX_FILE_CHARS)和输出目录(DIAGRAM_OUT_DIR).
便携式输出：渲染的图表作为图像内容返回，也保存为PNG文件。

它公开了三个工具：

工具	说明
`list_files`	列出本地文件夹或GitHub仓库中的文件（支持root+glob过滤）。
`read_file`	读取具有可配置最大长度的文件内容（本地或GitHub）。
`render_mermaid`	通过Kroki渲染美人鱼文本并返回 `ImageContent` （也保存到磁盘）。

1) `list_files`

返回给定源的文件列表(local / github)与 root + glob 过滤。

参数

source: "local" 或 "github"
root：默认值 "."
glob：默认值 "**/*"
repo_url：需要时 source="github"
ref：默认值 "main"
recursive：默认值 true

示例（本地）

{
  "source": "local",
  "root": ".",
  "glob": "**/*.py",
  "recursive": true
}

示例（github）

{
  "source": "github",
  "repo_url": "https://github.com/<owner>/<repo>",
  "ref": "main",
  "root": "src",
  "glob": "**/*.py",
  "recursive": true
}

2) `read_file`

读取具有长度限制的文件内容（本地或GitHub）。

参数

source: "local" 或 "github"
path：必填
repo_url：需要时 source="github"
ref：默认值 "main"
max_chars：默认值 MAX_FILE_CHARS

示例（本地）

{
  "source": "local",
  "path": "src/server/server.py",
  "max_chars": 200000
}

示例（github）

{
  "source": "github",
  "repo_url": "https://github.com/<owner>/<repo>",
  "ref": "main",
  "path": "README.md",
  "max_chars": 200000
}

3) `render_mermaid`

接受Mermaid文本，通过Kroki将其渲染为PNG，返回 ImageContent，并将文件保存到磁盘。

参数

mermaid：required（string）--美人鱼图源文本
title：optional（string）--用于导出输出文件名（将被净化）

退货

ImageContent 包含渲染的PNG字节
还将PNG文件写入 PROJECT_ROOT/DIAGRAM_OUT_DIR/<filename>.png

行为

如果 mermaid 是空的→ error
文件保存在 DIAGRAM_OUT_DIR （里面 PROJECT_ROOT)
输出路径：图像保存到 PROJECT_ROOT/DIAGRAM_OUT_DIR/<filename>.png （默认输出目录： ./diagrams/).
文件名：来源于 title （经过消毒以确保文件系统安全）。如果 title 缺少，将使用默认名称。
名称冲突：如果 <filename>.png 已存在，将被覆盖。

示例

{
  "mermaid": "flowchart LR\nA[Start] --> B[Build]\nB --> C[Run]\n",
  "title": "my_flow"
}

需求

Python 3.10+（推荐）
互联网接入（适用于Kroki，使用时适用于GitHub github 来源）

项目结构

.
├── README.md
├── Dockerfile
├── pyproject.toml
├── .env.example
├── .gitignore
└── src/
    ├── config.py                  # Env/config defaults
    ├── server/                    # MCP server entrypoint
    │   └── server.py
    ├── tools/                     # MCP tools (list/read/render)
    │   ├── list_files.py
    │   ├── read_file.py
    │   └── render_mermaid.py
    ├── sources/                   # File sources behind one interface (Local / GitHub)
    │   ├── local_source.py
    │   ├── github_source.py
    │   └── source_factory.py
    ├── core/                      # Contracts + primitives (interfaces, errors, cache, pacing, rate limiting)
    │   ├── interfaces.py          # Source contract that shapes all implementations
    │   ├── models.py
    │   ├── errors.py
    │   ├── paths.py               # Shared path normalization + glob semantics (incl. **)
    │   ├── cache.py
    │   ├── pacing.py
    │   └── rate_limiter.py
    ├── clients/                   # External API clients (kept thin; shared policies live in core)
    │   ├── kroki_client.py
    │   └── github/
    │       ├── client.py          # HTTP + policy (cache/rate/pacing)
    │       ├── inputs.py          # normalize/validate inputs
    │       └── refs.py            # resolve refs (+ fallback)
    ├── resources/                 # Mermaid styles and small assets
    └── prompts/                   # Server-side canonical prompts

有关架构的详细信息，请参阅：建筑.md

Docker（可选）

使用Docker构建和运行（示例）：

# build image
docker build -t mermaid-mcp:latest .

# run container (example, mount project root and set env vars)
docker run --rm -it \
  -v "$PWD":/app \
  -e PROJECT_ROOT=/app \
  -e KROKI_BASE_URL=https://kroki.io \
  -e KROKI_TIMEOUT=20 \
  -e DIAGRAM_OUT_DIR=diagrams \
  mermaid-mcp:latest

安装和设置

1）克隆仓库

git clone <REPO_URL>
cd <REPO_DIR>

2）创建venv+安装依赖项

Windows（PowerShell）：

python -m venv .venv
.\.venv\Scripts\Activate.ps1
pip install .[dev]

Windows（CMD）：

python -m venv .venv
.venv\Scripts\activate.bat
pip install .[dev]

macOS/Linux：

python -m venv .venv
source .venv/bin/activate
pip install .[dev]

这将安装运行时依赖项和开发附加项（测试）。

3）配置（环境变量）

您可以在启动服务器的shell或MCP客户端配置中设置env变量。

必需/推荐

变量	描述	使用人
`PROJECT_ROOT`	允许服务器访问的本地项目根目录（安全边界）	`local_source`
`KROKI_BASE_URL`	例如。 `https://kroki.io`	`render_mermaid`
`KROKI_TIMEOUT`	Kroki请求超时	`render_mermaid`
`DIAGRAM_OUT_DIR`	在哪里保存PNG(必须在里面 `PROJECT_ROOT`)	`render_mermaid`
`MAX_FILE_CHARS`	从文件读取的最大字符数（防止大量读取）	`read_file`

可选的

变量	描述	使用人
`HTTP_VERIFY`	验证SSL证书（根据需要）	`server`
`GITHUB_TOKEN`	建议避免GitHub速率限制；如果设置，则添加 `Authorization` 头球 `src/clients/github/client.py`

示例（Windows）

set PROJECT_ROOT=.
set KROKI_BASE_URL=https://kroki.io
set KROKI_TIMEOUT=20
set DIAGRAM_OUT_DIR=diagrams
set MAX_FILE_CHARS=200000

示例（macOS/Linux）

export PROJECT_ROOT=.
export KROKI_BASE_URL=https://kroki.io
export KROKI_TIMEOUT=20
export DIAGRAM_OUT_DIR=diagrams
export MAX_FILE_CHARS=200000

4）运行服务器（stdio）

python src/server/server.py

服务器名称： `mermaid-mcp`

连接MCP客户端（示例：Claude Desktop）

任何可以启动本地stdio服务器的MCP客户端都可以使用此项目。下面是Claude Desktop的示例配置。

1）找到Claude桌面配置

Claude Desktop将MCP服务器定义存储在JSON配置文件中。

常见位置：

视窗: %APPDATA%\Claude\claude_desktop_config.json
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

如果文件还不存在，请创建它。

2）将此服务器添加到 `claude_desktop_config.json`

示例（Windows）：

{
  "mcpServers": {
    "mermaid-mcp": {
      "command": "C:\\Users\\<YOU>\\path\\to\\repo\\.venv\\Scripts\\python.exe",
      "args": [
        "C:\\Users\\<YOU>\\path\\to\\repo\\src\\server\\server.py"
      ],
      "env": {
        "PROJECT_ROOT": "C:\\Users\\<YOU>\\path\\to\\repo",
        "KROKI_BASE_URL": "https://kroki.io",
        "KROKI_TIMEOUT": "20",
        "DIAGRAM_OUT_DIR": "diagrams",
        "MAX_FILE_CHARS": "200000"
      }
    }
  }
}

3）重新启动克劳德桌面

保存配置文件后，完全关闭Claude Desktop并重新打开，以便加载服务器。

4）验证工具是否可用

打开Claude Desktop，检查服务器工具是否显示（例如。 list_files, read_file, render_mermaid).

使用规范提示

该项目包括一个规范的系统提示，用于以一致的、工具驱动的方式生成Mermaid图。提示已在MCP服务器上以以下名称注册 generate_mermaid_canonical 并且在 src/prompts/mermaid_prompt.py.

使用它的两种常见方法：

客户端支持的提示（推荐）：如果您的MCP客户端支持服务器端提示，请选择服务器 mermaid-mcp，选择名为的提示 generate_mermaid_canonical 从提示列表中，在调用工具之前，将其作为代理的系统/指令运行。使用服务器注册的提示可确保代理始终获得最新的提示文本。
复制粘贴：如果您的客户端不支持服务器端提示，请打开 src/prompts/mermaid_prompt.py，复制提示文本，并将其粘贴到代理的系统消息中，或将其保存为本地预设。请记住，当存储库提示更改时，您需要更新本地副本。

笔记：

规范提示强制执行严格的工具使用，并需要规范样式资源 mermaid://styles/blue-flowchart 可以读取并原封不动地嵌入到生成的图表中。
提示希望代理遵循管道： list_files → read_file → 生成美人鱼→ render_mermaid.

测试

运行测试套件：

pytest -q

端到端示例：

这是一个完整、真实的流程，展示了预期的管道： list_files → read_file → 生成美人鱼→ render_mermaid.

步骤1——列出GitHub仓库中的文件

{
  "source": "github",
  "repo_url": "https://github.com/<owner>/<repo>",
  "ref": "main",
  "root": "src",
  "glob": "**/*.py",
  "recursive": true
}

第二步——挑选一小部分重要文件（5-12）

示例选择（您根据仓库包含的内容进行选择）：

src/server/server.py
src/tools/list_files.py
src/tools/read_file.py
src/tools/render_mermaid.py
src/core/interfaces.py
src/clients/github/client.py
src/clients/github/refs.py
src/core/cache.py
src/core/pacing.py
src/core/rate_limiter.py
src/clients/kroki_client.py

步骤3——读取所选文件

{
  "source": "github",
  "repo_url": "https://github.com/<owner>/<repo>",
  "ref": "main",
  "path": "src/server/server.py",
  "max_chars": 200000
}

第四步——根据你读到的内容生成美人鱼

flowchart LR
  A[Agent / Client] -->|list_files| B[MCP Server]
  A -->|read_file| B
  B --> C[Local/GitHub Source]
  B --> D[Mermaid generation]
  B -->|render_mermaid| E[Kroki API]
  E --> F[PNG bytes]
  F --> A

步骤5--将Mermaid渲染为PNG

{
  "mermaid": "<paste the Mermaid from Step 4 (or the generated Mermaid diagram)>",
  "title": "repo_to_diagram"
}

安全性和可预测行为

有关安全性和可预测的行为，请参阅：安全边界

故障排除

"Missing repo_url for github source" → 你忘了 repo_url 随着 source="github"
"Missing file path" → 你打电话来了 read_file 没有 path
"Access outside project root is not allowed" → 试图在外面阅读 PROJECT_ROOT
"DIAGRAM_OUT_DIR must be within PROJECT_ROOT" → 输出目录不在内部 PROJECT_ROOT

未来的工作（其他来源）

接下来，我们计划支持本地文件夹和GitHub之外的更多输入源，这样服务器就可以从其他代码主机和内容提供商（例如GitLab、Bitbucket、Azure DevOps Repos，以及ZIP存档或通过URL的单个文件）生成Mermaid图。

这将建立在统一的基础上 Source 抽象：每个新源代码都将实现相同的合约(list_files 和 read_file)，虽然工具保持不变，但扩展支持只需要添加新的源代码实现并在工厂中注册即可。

使用说明

mermaid mcp——一个mcp服务器，用于绘制任何项目的图表（本地/GitHub→ 美人鱼→ PNG)

为什么选择此服务器

主要特点

它公开了三个工具：

1) list_files

参数

示例（本地）

示例（github）

2) read_file

参数

示例（本地）

示例（github）

3) render_mermaid

参数

退货

行为

示例

需求

项目结构

Docker（可选）

安装和设置

1） 克隆仓库

2） 创建venv+安装依赖项

Windows（PowerShell）：

Windows（CMD）：

macOS/Linux：

3） 配置（环境变量）

必需/推荐

可选的

4） 运行服务器（stdio）

服务器名称： mermaid-mcp

连接MCP客户端（示例：Claude Desktop）

1） 找到Claude桌面配置

2） 将此服务器添加到 claude_desktop_config.json

3） 重新启动克劳德桌面

4） 验证工具是否可用

使用规范提示

测试

端到端示例：

步骤1——列出GitHub仓库中的文件

第二步——挑选一小部分重要文件（5-12）

步骤3——读取所选文件

第四步——根据你读到的内容生成美人鱼

步骤5--将Mermaid渲染为PNG

安全性和可预测行为

故障排除

未来的工作（其他来源）

相关 MCP

代码分析与可视化工具

目录树可视化工具

结构化文档系统构建工具

GitHub仓库分析工具

架构图生成器

文档管理集成服务

1) `list_files`

2) `read_file`

3) `render_mermaid`

1）克隆仓库

2）创建venv+安装依赖项

3）配置（环境变量）

4）运行服务器（stdio）

服务器名称： `mermaid-mcp`

1）找到Claude桌面配置

2）将此服务器添加到 `claude_desktop_config.json`

3）重新启动克劳德桌面

4）验证工具是否可用