第26章 MCP Server——Mermaid MCP 服务器使用指南
Mermaid MCP Server
Mermaid MCP Server 支持 AI 助手无缝创建、验证并渲染 Mermaid 图表,同时提供与 Mermaid 账户的完整集成,实现高级图表管理功能。当你要求 AI 助手创建流程图、序列图或其他 Mermaid 图表时,该服务器会自动处理整个流程,包括语法验证、PNG 图片生成、交互式 Playground 链接,以及与你的 Mermaid 项目直接集成。
Mermaid MCP Server 支持多种传输模式,且每次工具调用都需要 Mermaid 账户认证。认证是免费的——你可以注册一个免费的 Mermaid 账户(Basic 等级)即可开始使用。你可以通过支持 OAuth 发现的客户端(如 VS Code、Cursor、Antigravity(通过 mcp-remote))自动通过 OAuth 2.1 及动态客户端注册完成认证,或者手动将 Mermaid 令牌粘贴到客户端配置中。详情请参见下文“认证设置”。
可用的传输类型:
HTTP:使用 "type": "http" 访问 https://mcp.mermaid.ai/mcp
SSE(Server-Sent Events):使用 "type": "sse" 访问 https://mcp.mermaid.ai/sse
认证要求:每次工具调用都需有效的 Mermaid 登录——免费创建——可通过自动 OAuth 或手动配置的 Authorization 请求头完成。
可用工具
以下列出的所有工具均需 Mermaid 认证(OAuth 登录或手动令牌)。认证免费:使用 Basic 版 Mermaid 账户即可,无需付费计划。
核心验证与渲染工具
validate_and_render_mermaid_diagram - 验证 Mermaid 语法并将图表渲染为带 Mermaid 实时链接的 PNG 图像
get_diagram_title - 为 Mermaid 图表生成描述性标题
get_diagram_summary - 创建图表内容的简洁摘要
list_tools - 列出所有可用的 MCP 工具
Mermaid 集成工具
list_mermaid_chart_projects - 列出 Mermaid 账户中的所有项目
list_mermaid_chart_diagrams - 列出特定项目中的图表
create_mermaid_chart_diagram - 在 Mermaid 中创建新图表
get_mermaid_chart_diagram - 从 Mermaid 获取特定图表
update_mermaid_chart_diagram - 更新 Mermaid 中现有图表
# 安装与配置 如果你使用的客户端支持 OAuth 自动发现(如 VS Code、Cursor、通过 mcp-remote 的 Antigravity 等),可以直接使用下面不带 header 的简单配置——首次调用工具时会自动弹出浏览器登录/授权页面,无需在配置中保存 token。带 Authorization header 的示例则适用于手动配置 token 认证的场景。 VS Code(配合 GitHub Copilot 或其他 MCP 扩展) HTTP Streamable 模式(适用于远程服务器): { "servers": { "mermaid-mcp": { "url": "https://mcp.mermaid.ai/mcp", "type": "http" } } } HTTP 模式 + 认证(适用于 Mermaid 集成): { "servers": { "mermaid-mcp": { "url": "https://mcp.mermaid.ai/mcp", "type": "http", "headers": { "Authorization": "YOUR_MERMAID_TOKEN_HERE" } } } } SSE 模式 + 认证(适用于实时连接): { "servers": { "mermaid-mcp": { "url": "https://mcp.mermaid.ai/sse", "type": "sse", "headers": { "Authorization": "YOUR_MERMAID_TOKEN_HERE" } } } } Cursor HTTP Streamable 模式(适用于远程服务器): { "mcpServers": { "mermaid-mcp": { "transport": "http", "url": "https://mcp.mermaid.ai/mcp" } } } HTTP 模式 + 认证(适用于 Mermaid 集成): { "mcpServers": { "mermaid-mcp": { "transport": "http", "url": "https://mcp.mermaid.ai/mcp", "headers": { "Authorization": "YOUR_MERMAID_TOKEN_HERE" } } } } SSE 模式 + 认证(适用于 Mermaid 集成): { "mcpServers": { "mermaid-mcp": { "transport": "sse", "url": "https://mcp.mermaid.ai/sse", "headers": { "Authorization": "YOUR_MERMAID_TOKEN_HERE" } } } } 带认证的 Antigravity 配置 前置条件: 在 Antigravity IDE 中连接我们的远程 MCP 服务器需要以下依赖: Node.js mcp-remote 远程 MCP 服务器(通过 mcp-remote 代理): { "mcpServers": { "mermaid": { "command": "npx", "args": [ "-y", "mcp-remote", "--header", "Authorization:YOUR_MERMAID_TOKEN_HERE", "https://mcp.mermaid.ai/mcp"] } } } 注意:Antigravity 目前需要使用 mcp-remote 代理来连接远程 MCP 服务器。直接支持远程 URL 的功能尚未正常工作,可能在后续版本中修复。请查阅 Antigravity MCP 文档以获取最新的配置选项。 认证设置 每次调用工具都需要登录 Mermaid 账户。注册免费——基础(Basic)层级不收取费用。认证方式有两种: 选项 1:OAuth 登录(推荐) 如果你的 MCP 客户端支持 OAuth 发现,则无需手动配置令牌。首次调用工具时,会弹出一个浏览器窗口要求你登录 Mermaid 账户。登录成功后,客户端将自动保持认证状态——无需在配置文件中添加令牌。 直接使用上述无 header 的纯配置示例即可。 选项 2:手动基于令牌的认证(仍支持) 获取令牌:访问你的 Mermaid 账户设置并生成 API 令牌 添加到配置:如上述示例所示,在 Authorization 头中包含该令牌 替换占位符:将 YOUR_MERMAID_TOKEN_HERE 替换为你的实际令牌 如果令牌缺失或无效,且 OAuth 登录未完成,所有工具调用将被拒绝。 工作原理 当 AI 助手(如 GitHub Copilot 或 ChatGPT)支持 MCP 时,它会自动检测你配置的服务器。当你发出诸如“为结账流程创建时序图”这样的请求时, 它会自动: 生成 Mermaid 语法 将其发送至 Mermaid MCP 服务器进行验证和渲染 返回可直接使用的 PNG 和 SVG 文件以及一个交互式 playground 链接 带认证功能时:还可以直接保存到你的 Mermaid 项目中,列出你现有的图表,并管理你的图表库
你将获得什么 每次请求图表,你都会得到: - 渲染好的 PNG 图片和 SVG 图片:可直接用于演示或文档的高质量图表 - 干净的 Mermaid 代码:格式规范、便于复制和修改的语法 - 交互式 Playground 链接:点击即可在 Mermaid 高级编辑器中编辑图表 - Mermaid 集成(需认证):直接访问你的项目,可在账户中保存、更新和管理图表
故障排查与支持 遇到问题时: - 检查你的 MCP client 配置是否与上面的示例一致 - 确认 server URL 可访问(托管部署时) - OAuth 问题:如果登录弹窗没有出现,请确认你的 client 支持 OAuth discovery;否则改用手动 token 认证 - 认证问题:确保你的 Mermaid token 有效,且 Authorization header 格式正确 - 权限错误:确认你的 token 具备执行相关操作所需的权限 - 配置修改后重启你的 AI 助手/IDE - 更多配置步骤请查阅 MCP client 文档 - 遇到问题或需要帮助请联系我们
想升级你的工作流?把 Mermaid MCP Server 接入你的 AI 助手,立即开始生成专业图表,并完整集成你的 Mermaid 账户,实现高级图表管理。