SuperAPI AI 工具集
合作ENAI 行业资讯收藏
全部工具AI编程工具claude-mermaid

claude-mermaid

claude-mermaid 是一个 MCP 服务器，用于在 Claude Code 中渲染 Mermaid 图表，支持实时重载、多种主题以及 SVG、PNG 或 PDF 导出。它会在浏览器中自动渲染图表，并随着编辑实时更新，适合迭代式图表开发与文档工作流。主要特性包括：编辑时图表自动刷新、可导出为 SVG/PNG/PDF、支持 default、forest、dark、neutral 主题、可自定义尺寸与背景色、支持拖拽平移与缩放、可从浏览器直接下载 SVG 或 PNG、可通过 preview_id 同时维护多个预览、实时预览文件持久化存储在 ~/.config/claude-mermaid/live。该项目以插件形式安装（推荐）或通过 npm 安装，也可配置到其他 MCP 兼容客户端。

访问官网

工具介绍

用途

claude-mermaid 是一个 MCP（Model Context Protocol）服务器，用于在 Claude Code 中渲染 Mermaid 图表，并带有实时重载功能与内置的专家指导技能。它会在浏览器中自动渲染图表，并随着你的修改实时更新，适合迭代式图表开发与文档工作流。

主要能力

  • 实时重载：编辑图表时，浏览器中的图表自动刷新。
  • 多种保存格式：可导出为 SVG、PNG 或 PDF。
  • 主题：可选择 default、forest、dark 或 neutral 主题。
  • 可自定义：可控制尺寸、缩放和背景颜色。
  • 交互式预览：可拖拽平移图表、使用浏览器缩放、一键重置位置。
  • 浏览器导出：可直接从预览界面下载 SVG 或 PNG。
  • 多预览：使用 preview_id 同时处理多个图表。
  • 持久化工作文件：实时预览存储在 ~/.config/claude-mermaid/live 下。
  • 内置技能：包含一个 Claude 技能，提供创建图表的最佳实践和专家指导。

安装方式

插件安装（推荐）

在 Claude Code 中添加 marketplace 并安装插件，然后重启 Claude Code 以激活插件。

验证安装：

插件安装：MCP 服务器会自动配置，只需验证 MCP 服务器列表中出现 mermaid 即可。

npm 安装：需手动配置 MCP 服务器，验证后应显示 mermaid: claude-mermaid - ✓ Connected。

其他 MCP 客户端配置

虽然该服务器针对 Claude Code 优化，但也可用于任何 MCP 兼容客户端，例如 Codex、Cursor、Cline（VSCode 扩展）、Windsurf、Gemini CLI 等。对于任何 MCP 兼容客户端，使用标准配置，命令 claude-mermaid 应在安装后位于 PATH 中。

注意：某些客户端可能需要可执行文件的完整路径。可通过 which claude-mermaid（Unix/macOS）或 where claude-mermaid（Windows）查找路径，并在配置中使用绝对路径。

使用方式

直接要求 Claude Code 自然地创建 Mermaid 图表。当作为插件安装时，内置的 mermaid-diagrams 技能会提供专家指导、最佳实践和自动工作流管理。

工具与参数：

MCP 服务器暴露两个工具：

  • mermaid_preview：渲染并打开实时预览

    • diagram（字符串，必填）：Mermaid 图表代码
    • preview_id（字符串，必填）：本次预览会话的标识符，用于同时处理多个图表（如 architecture、flow）
    • format（字符串，默认 svg）：可选 svg、png、pdf。实时预览仅支持 svg。
    • theme（字符串，默认 default）：可选 default、forest、dark、neutral。
    • background（字符串，默认 white）：背景色，例如 transparent、white、#F0F0F0。
    • width（数字，默认 800）：图表宽度（像素）。
    • height（数字，默认 600）：图表高度（像素）。
    • scale（数字，默认 2）：缩放因子，用于更高品质输出。

  • mermaid_save：将当前实时图表保存到指定路径

    • save_path（字符串，必填）：目标路径（如 ./docs/diagram.svg）。
    • preview_id（字符串，必填）：必须与 mermaid_preview 中使用的 preview_id 匹配。
    • format（字符串，默认 svg）：可选 svg、png、pdf。如果该格式的实时工作文件尚不存在，会在保存前按需渲染。

实时重载工作原理：

  1. 首次渲染：在浏览器中打开 http://localhost:3737/{preview_id}
  2. 做出修改：通过 Claude Code 编辑图表
  3. 自动刷新：浏览器通过 WebSocket 检测变更并重新加载
  4. 状态指示：绿点 = 已连接，红点 = 正在重连

实时服务器使用端口 3737-3747，会自动寻找可用端口。

实时预览控制：

  • 平移：点击并拖拽图表移动
  • 缩放：使用浏览器缩放（Ctrl/Cmd + +/- 或触控板捏合缩放）
  • 重置位置：点击状态栏中的 ⊙ 按钮重新居中图表
  • 导出：点击 ⬇ 按钮下载 SVG 或 PNG

实时预览仅支持 svg 格式；PNG/PDF 渲染时无实时重载。

对于序列图，Mermaid 不支持在 sequenceDiagram 内部使用样式指令。

独立服务器：

可以使用 --serve 标志在不使用 AI 代理的情况下启动预览服务器，这会在浏览器中打开图表库，包含所有先前渲染的图表，适用于在 Claude Code 会话之外浏览和导出图表。

适用场景

  • 迭代式图表开发
  • 文档工作流
  • 需要同时维护多个图表的场景
  • 需要导出多种格式（SVG、PNG、PDF）的图表

限制

  • 实时预览仅支持 svg 格式。
  • 序列图不支持在 sequenceDiagram 内部使用样式指令。
  • 某些客户端可能需要可执行文件的完整路径。

故障排除

  • 错误：Cannot find package 'puppeteer'：这是罕见的环境特定问题。可尝试全局安装 npm install -g claude-mermaid，或重新安装插件（/plugin uninstall claude-mermaid，然后 /plugin install claude-mermaid@claude-mermaid）。
  • 服务器未连接：
  • 权限被拒绝错误：
  • 端口已被占用：服务器使用端口 3737-3747，会自动寻找可用端口。可用 lsof -i :3737-3747 检查占用。
  • 图表未渲染或实时重载不工作：服务器日志位于 ~/.config/claude-mermaid/logs/，其中 mcp.log 记录工具请求和图表渲染，web.log 记录 HTTP/WebSocket 连接和实时重载。可在 MCP 配置中启用调试日志。可用日志级别：DEBUG、INFO（默认）、WARN、ERROR、OFF。

其他信息

  • 欢迎贡献，可提交 Pull Request。
  • 许可证：MIT，详见 LICENSE 文件。
  • 相关项目：preview-skills——用于在浏览器中可视化文件（markdown、csv、json、mermaid 等）的预览技能。
  • 托管部署可在 Fronteir AI 上获得。

同类工具

查看分类