Mermaid MCP Server

Converte diagramas Mermaid para imagens PNG ou SVG.

GitHub
235
Experimente este MCPPatrocinado

Documentação

Mermaid MCP Server

Um servidor Model Context Protocol (MCP) que converte diagramas Mermaid em imagens PNG ou arquivos SVG. Este servidor permite que assistentes de IA e outras aplicações gerem diagramas visuais a partir de descrições textuais usando a sintaxe markdown do Mermaid.

Recursos

  • Converte código de diagrama Mermaid em imagens PNG ou arquivos SVG
  • Suporta múltiplos temas de diagrama (default, forest, dark, neutral)
  • Cores de fundo personalizáveis
  • Usa Puppeteer para renderização de alta qualidade em navegador headless
  • Implementa o protocolo MCP para integração perfeita com assistentes de IA
  • Opções de saída flexíveis: retorna imagens/SVG diretamente ou salva em disco
  • Tratamento de erros com mensagens de erro detalhadas

Como Funciona

O servidor usa Puppeteer para iniciar um navegador headless, renderizar o diagrama Mermaid em SVG e, opcionalmente, capturar uma captura de tela do diagrama renderizado. O processo envolve:

  1. Iniciar uma instância de navegador headless
  2. Criar um template HTML com o código Mermaid
  3. Carregar a biblioteca Mermaid.js
  4. Renderizar o diagrama em SVG
  5. Salvar o SVG diretamente ou capturar uma captura de tela como PNG
  6. Retornar a imagem/SVG diretamente ou salvá-la em disco

Build

npx tsc

Uso

Uso com Claude desktop

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

Uso com Cursor e Cline

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

Você pode encontrar uma lista de diagramas mermaid em ./diagrams, criados usando o agente Cursor com o prompt: "generate mermaid diagrams and save them in a separate diagrams folder explaining how renderMermaidPng work"

Executar com inspector

Execute o servidor com inspector para testes e depuração:

npx @modelcontextprotocol/inspector node dist/index.js

O servidor iniciará e ficará ouvindo em stdio por mensagens do protocolo MCP.

Saiba mais sobre o inspector aqui.

Instalação via Smithery

Para instalar o Mermaid Diagram Generator para Claude Desktop automaticamente via Smithery:

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

Ambientes Docker e Smithery

Ao executar em contêineres Docker (incluindo via Smithery), você pode precisar lidar com dependências do Chrome:

  1. O servidor agora tenta usar o navegador empacotado do Puppeteer por padrão

  2. Se você encontrar erros relacionados ao navegador, você tem duas opções:

    Opção 1: Durante a construção da imagem Docker:

    • Defina PUPPETEER_SKIP_CHROMIUM_DOWNLOAD=true ao instalar o Puppeteer
    • Instale Chrome/Chromium no seu contêiner Docker
    • Defina PUPPETEER_EXECUTABLE_PATH em tempo de execução para apontar para a instalação do Chrome

    Opção 2: Usar o Chrome empacotado do Puppeteer:

    • Garanta que seu contêiner Docker tenha as dependências necessárias para o Chrome
    • Não é necessário definir PUPPETEER_SKIP_CHROMIUM_DOWNLOAD
    • O código usará o navegador empacotado automaticamente

Para usuários do Smithery, a versão mais recente deve funcionar sem configuração adicional.

API

O servidor expõe uma única ferramenta:

  • generate: Converte código de diagrama Mermaid em uma imagem PNG ou arquivo SVG
    • Parâmetros:
      • code: O código do diagrama Mermaid a ser renderizado
      • theme: (opcional) Tema do diagrama. Opções: "default", "forest", "dark", "neutral"
      • backgroundColor: (opcional) Cor de fundo do diagrama, ex.: 'white', 'transparent', '#F0F0F0'
      • outputFormat: (opcional) Formato de saída do diagrama. Opções: "png", "svg" (padrão: "png")
      • name: Nome do arquivo gerado (obrigatório quando CONTENT_IMAGE_SUPPORTED=false)
      • folder: Caminho absoluto para salvar a imagem/SVG (obrigatório quando CONTENT_IMAGE_SUPPORTED=false)

O comportamento da ferramenta generate depende da variável de ambiente CONTENT_IMAGE_SUPPORTED:

  • Quando CONTENT_IMAGE_SUPPORTED=true (padrão): A ferramenta retorna a imagem/SVG diretamente na resposta
  • Quando CONTENT_IMAGE_SUPPORTED=false: A ferramenta salva a imagem/SVG na pasta especificada e retorna o caminho do arquivo

Variáveis de Ambiente

  • CONTENT_IMAGE_SUPPORTED: Controla se as imagens são retornadas diretamente na resposta ou salvas em disco
    • true (padrão): As imagens são retornadas diretamente na resposta
    • false: As imagens são salvas em disco, exigindo os parâmetros name e folder

Exemplos

Uso Básico

// 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]"
}

Com Tema e Cor de Fundo

// 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"
}

Salvando em Disco (quando CONTENT_IMAGE_SUPPORTED=false)

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

Gerando Saída SVG

// Generate a state diagram as SVG
{
  "code": "stateDiagram-v2\n    [*] --> Still\n    Still --> [*]\n    Still --> Moving\n    Moving --> Still\n    Moving --> Crash\n    Crash --> [*]",
  "outputFormat": "svg",
  "name": "state_diagram",
  "folder": "/path/to/diagrams"
}

FAQ

O Claude desktop já não suporta mermaid via canvas?

Sim, mas ele não suporta as opções theme e backgroundColor. Além disso, ter um servidor dedicado facilita a criação de diagramas mermaid com diferentes clientes MCP.

Por que preciso especificar CONTENT_IMAGE_SUPPORTED=false ao usar com Cursor?

O Cursor ainda não suporta imagens inline em respostas.

Publicação

Este projeto usa GitHub Actions para automatizar o processo de publicação no npm.

Método 1: Usando o Script de Release (Recomendado)

  1. Certifique-se de que todas as suas alterações foram commitadas e enviadas

  2. Execute o script de release com um número de versão específico ou um incremento de versão semântica:

    # 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. O script irá:

    • Validar o formato da versão ou o incremento semântico
    • Verificar se você está na branch main
    • Detectar e alertar sobre incompatibilidades de versão entre arquivos
    • Atualizar todas as referências de versão de forma consistente (package.json, package-lock.json e index.ts)
    • Criar um único commit com todas as alterações de versão
    • Criar e enviar uma tag git
    • O workflow do GitHub então compilará e publicará automaticamente no npm

Método 2: Processo Manual

  1. Atualize seu código e faça commit das alterações
  2. Crie e envie uma nova tag com o número da versão: 
    git tag v0.1.4  # Use the appropriate version number
git push origin v0.1.4
  3. O workflow do GitHub irá automaticamente:
    • Compilar o projeto
    • Publicar no npm com a versão da tag

Nota: Você precisa configurar o segredo NPM_TOKEN nas configurações do seu repositório GitHub. Para fazer isso:

  1. Gere um token de acesso npm com permissões de publicação
  2. Vá para seu repositório GitHub → Settings → Secrets and variables → Actions
  3. Crie um novo segredo de repositório chamado NPM_TOKEN com seu token npm como valor

Badges

smithery badge

mermaid-mcp-server MCP server

Licença

MIT