Skip to main content
Glama
deenesjakoruzh
peng-shawn

mermaid-mcp-server

by peng-shawn
OverviewSchemaSourceRelated ServersDiscussionsAdmin
JavaScript
Hybrid

美人鱼 MCP 服务器

一个模型上下文协议 (MCP) 服务器，用于将 Mermaid 图表转换为 PNG 图像。该服务器允许 AI 助手和其他应用程序使用 Mermaid Markdown 语法从文本描述生成可视化图表。

特征

  • 将美人鱼图代码转换为 PNG 图像

  • 支持多种图表主题（默认、森林、深色、中性）

  • 可自定义的背景颜色

  • 使用 Puppeteer 实现高质量无头浏览器渲染

  • 实施 MCP 协议，实现与 AI 助手的无缝集成

  • 灵活的输出选项：直接返回图像或保存到磁盘

  • 带有详细错误消息的错误处理

Related MCP server: Mermaid MCP Server

工作原理

服务器使用 Puppeteer 启动无头浏览器，将美人鱼图渲染为 SVG，并截取渲染图的屏幕截图。该过程包括：

  1. 启动无头浏览器实例

  2. 使用 Mermaid 代码创建 HTML 模板

  3. 加载 Mermaid.js 库

  4. 将图表渲染为 SVG

  5. 将渲染后的 SVG 截图为 PNG

  6. 直接返回图像或将其保存到磁盘

建造

npx tsc

用法

与 Claude 桌面一起使用

"mcpServers": {
  "mermaid": {
    "command": "npx",
    "args": [
      npx @peng-shawn/mermaid-mcp-server
    ]
  }
}

与 Cursor 和 Cline 一起使用

env CONTENT_IMAGE_SUPPORTED=false npx @peng-shawn/mermaid-mcp-server

您可以在./diagrams下找到美人鱼图列表，它们是使用 Cursor 代理创建的，提示为：“生成美人鱼图并将其保存在单独的图表文件夹中，解释 renderMermaidPng 如何工作”

与检查器一起运行

使用检查器运行服务器进行测试和调试：

npx @modelcontextprotocol/inspector node dist/index.js

服务器将启动并在 stdio 上监听 MCP 协议消息。

在此处了解有关检查员的更多信息。

通过 Smithery 安装

要通过Smithery自动安装 Claude Desktop 的美人鱼图表生成器：

npx -y @smithery/cli install @peng-shawn/mermaid-mcp-server --client claude

Docker 和 Smithery 环境

在 Docker 容器中运行时（包括通过 Smithery），您可能需要处理 Chrome 依赖项：

  1. 服务器现在默认尝试使用 Puppeteer 捆绑的浏览器

  2. 如果遇到与浏览器相关的错误，您有两种选择：

    选项 1：在 Docker 镜像构建期间：

    • 安装 Puppeteer 时设置PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true

    • 在 Docker 容器中安装 Chrome/Chromium

    • 在运行时设置PUPPETEER_EXECUTABLE_PATH以指向 Chrome 安装

    选项 2：使用 Puppeteer 捆绑的 Chrome：

    • 确保您的 Docker 容器具有 Chrome 所需的依赖项

    • 无需设置PUPPETEER_SKIP_CHROMIUM_DOWNLOAD

    • 代码将自动使用捆绑的浏览器

对于 Smithery 用户来说，最新版本无需额外配置即可使用。

API

服务器公开一个工具：

  • generate ：将美人鱼图代码转换为 PNG 图像

    • 参数：

      • code ：要渲染的美人鱼图代码

      • theme ：（可选）图表主题。选项：“默认”、“森林”、“深色”、“中性”

      • backgroundColor ：（可选）图表的背景颜色，例如“白色”、“透明”、“#F0F0F0”

      • name ：生成的文件的名称（CONTENT_IMAGE_SUPPORTED=false 时必需）

      • folder ：保存图像的绝对路径（CONTENT_IMAGE_SUPPORTED=false 时必需）

generate工具的行为取决于CONTENT_IMAGE_SUPPORTED环境变量：

  • 当CONTENT_IMAGE_SUPPORTED=true （默认）时：工具直接在响应中返回图像

  • 当CONTENT_IMAGE_SUPPORTED=false时：工具将图片保存到指定文件夹，并返回文件路径

环境变量

  • CONTENT_IMAGE_SUPPORTED ：控制图像是否直接在响应中返回或保存到磁盘

    • true （默认值）：图像直接在响应中返回

    • false ：图像保存到磁盘，需要name和folder参数

示例

基本用法

// Generate a flowchart with default settings
{
  "code": "flowchart TD\n    A[Start] --> B{Is it?}\n    B -->|Yes| C[OK]\n    B -->|No| D[End]"
}

带有主题和背景颜色

// Generate a sequence diagram with forest theme and light gray background
{
  "code": "sequenceDiagram\n    Alice->>John: Hello John, how are you?\n    John-->>Alice: Great!",
  "theme": "forest",
  "backgroundColor": "#F0F0F0"
}

保存到磁盘（当 CONTENT_IMAGE_SUPPORTED=false 时）

// Generate a class diagram and save it to disk
{
  "code": "classDiagram\n    Class01 <|-- AveryLongClass\n    Class03 *-- Class04\n    Class05 o-- Class06",
  "theme": "dark",
  "name": "class_diagram",
  "folder": "/path/to/diagrams"
}

常问问题

Claude 桌面不是已经通过画布支持美人鱼了吗？

是的，但它不支持theme和backgroundColor选项。另外，拥有专用服务器可以更轻松地使用不同的 MCP 客户端创建美人鱼图表。

为什么在使用 Cursor 时需要指定 CONTENT_IMAGE_SUPPORTED=false？

Cursor 尚不支持响应中的内联图像。

出版

该项目使用 GitHub Actions 来自动化 npm 发布过程。

方法一：使用发布脚本（推荐）

  1. 确保所有更改都已提交并推送

  2. 使用特定版本号或语义版本增量运行发布脚本：

    # Using a specific version number
npm run release 0.1.4

# Using semantic version increments
npm run release patch  # Increments the patch version (e.g., 0.1.3 → 0.1.4)
npm run release minor  # Increments the minor version (e.g., 0.1.3 → 0.2.0)
npm run release major  # Increments the major version (e.g., 0.1.3 → 1.0.0)

  3. 该脚本将：

    • 验证版本格式或语义增量

    • 检查你是否在主分支上

    • 检测并警告文件之间的版本不匹配

    • 一致更新所有版本引用（package.json、package-lock.json 和 index.ts）

    • 创建包含所有版本更改的单个提交

    • 创建并推送 git 标签

    • GitHub 工作流程将自动构建并发布到 npm

方法二：手动处理

  1. 更新代码并提交更改

  2. 创建并推送带有版本号的新标签：

    git tag v0.1.4  # Use the appropriate version number
git push origin v0.1.4

  3. GitHub 工作流程将自动：

    • 构建项目

    • 使用标签中的版本发布到 npm

注意：您需要在 GitHub 仓库设置中设置NPM_TOKEN密钥。操作步骤如下：

  1. 生成具有发布权限的 npm 访问令牌

  2. 转到你的 GitHub 存储库 → 设置 → 机密和变量 → 操作

  3. 创建一个名为NPM_TOKEN的新存储库机密，并使用您的 npm 令牌作为值

徽章

铁匠徽章

执照

麻省理工学院

Available Tools

1 tool
generateC

Generate PNG image or SVG from mermaid markdown

ParametersJSON Schema
NameRequiredDescriptionDefault
backgroundColorNoBackground color for the diagram, e.g. 'white', 'transparent', '#F0F0F0' (optional)
codeYesThe mermaid markdown to generate an image from
folderNoAbsolute path to save the image to (optional)
nameNoName of the diagram (optional)
outputFormatNoOutput format for the diagram (optional, defaults to 'png')
themeNoTheme for the diagram (optional)

TDQS

C2.9/5.0
Behavior2/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 of behavioral disclosure. It mentions the tool generates images from mermaid markdown but doesn't cover important behavioral aspects like file system interactions (saving to a folder), performance characteristics, error handling, or any side effects. For a tool that writes files, this is a significant gap in transparency.

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—a single sentence that directly states the tool's function without any fluff. It's front-loaded and efficiently communicates the core purpose, making it easy for an agent to parse quickly.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness2/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, file output, no output schema) and lack of annotations, the description is insufficient. It doesn't explain what the tool returns, how errors are handled, or the implications of optional parameters like 'folder'. For a generative tool with file system operations, more context is needed for safe and effective use.

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 schema description coverage is 100%, meaning all parameters are well-documented in the schema itself. The description doesn't add any meaningful parameter semantics beyond what's already in the schema (e.g., it doesn't explain parameter interactions or provide examples). This meets the baseline for high schema coverage but doesn't enhance understanding.

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: 'Generate PNG image or SVG from mermaid markdown'. It specifies the verb ('Generate'), resource ('PNG image or SVG'), and source material ('mermaid markdown'), making the function unambiguous. However, since there are no sibling tools mentioned, it doesn't need to distinguish from alternatives, so it doesn't reach the highest 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, prerequisites, or context. It simply states what the tool does without indicating scenarios where it's appropriate or any limitations. This lack of usage context leaves the agent without operational guidance.

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. 1 tool updatev1.0.0
    • First observedgenerate
Deploy Server
One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

TDQS

B3.1/5.0

Scored across 1 tool

Disambiguation5/5

With only one tool, there is no possibility of ambiguity or overlap between tools. The tool's purpose is clearly defined and distinct by default.

Naming Consistency5/5

A single tool inherently has perfect naming consistency, as there are no other tools to compare against. The name 'generate' is simple and follows a verb-based pattern.

Tool Count2/5

One tool is too few for a server's purpose, as it severely limits functionality and suggests the server is under-scoped. A typical MCP server should offer multiple operations to handle a domain comprehensively.

Completeness2/5

The tool surface is severely incomplete for a mermaid diagramming domain. It only provides generation, missing essential operations like validation, editing, listing diagram types, or managing diagram states, which are necessary for agent workflows.

Maintenance

ActivityInactive
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

Appeared in Searches