mermaid-mcp-server Public

Servidor MCP para gerar diagramas Mermaid a partir de projetos (local/GitHub) e renderizar via Kroki.

Documentação

mermaid-mcp — um servidor MCP para diagramar qualquer projeto (Local/GitHub → Mermaid → PNG)

Mermaid MCP Server é um servidor MCP que ajuda agentes a transformar grandes bases de código (pastas locais ou repositórios GitHub) em diagramas Mermaid e renderizá-los como imagens PNG via Kroki, permitindo um entendimento rápido e confiável da estrutura e do fluxo de um projeto.

Por que este servidor

Ao trabalhar com uma nova base de código, é fácil perder tempo navegando entre pastas e arquivos. Este servidor fornece um fluxo de trabalho limpo e baseado em ferramentas para agentes descobrirem, lerem e visualizarem um projeto — sem adivinhar caminhos ou inventar estrutura.

Recursos principais

Fontes locais + GitHub: analise uma pasta de projeto local ou um repositório remoto.
Pipeline amigável para agentes: list_files → read_file → gerar Mermaid → render_mermaid.
Limite de acesso local seguro: leituras locais são restritas a PROJECT_ROOT.
Limites configuráveis: controle o tamanho máximo de arquivo (MAX_FILE_CHARS) e o diretório de saída (DIAGRAM_OUT_DIR).
Saída portátil: diagramas renderizados são retornados como conteúdo de imagem e também salvos como arquivos PNG.

Ele expõe três ferramentas:

Ferramenta	Descrição
`list_files`	Lista arquivos de uma pasta local ou repositório GitHub (suporta filtragem por raiz + glob).
`read_file`	Lê o conteúdo de arquivos (local ou GitHub) com um comprimento máximo configurável.
`render_mermaid`	Renderiza texto Mermaid via Kroki e retorna `ImageContent` (também salva em disco).

1) `list_files`

Retorna uma lista de arquivos para uma determinada fonte (local / github) com filtragem por root + glob.

Parâmetros

source: "local" ou "github"
root: padrão "."
glob: padrão "**/*"
repo_url: obrigatório quando source="github"
ref: padrão "main"
recursive: padrão true

Exemplo (local)

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

Exemplo (github)

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

2) `read_file`

Lê o conteúdo de arquivos (local ou GitHub) com um limite de comprimento.

Parâmetros

source: "local" ou "github"
path: obrigatório
repo_url: obrigatório quando source="github"
ref: padrão "main"
max_chars: padrão MAX_FILE_CHARS

Exemplo (local)

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

Exemplo (github)

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

3) `render_mermaid`

Aceita texto Mermaid, renderiza-o em PNG via Kroki, retorna ImageContent e salva o arquivo em disco.

Parâmetros

mermaid: obrigatório (string) — o texto-fonte do diagrama Mermaid
title: opcional (string) — usado para derivar o nome do arquivo de saída (será sanitizado)

Retornos

ImageContent contendo os bytes do PNG renderizado
Também grava o arquivo PNG em PROJECT_ROOT/DIAGRAM_OUT_DIR/<filename>.png

Comportamento

Se mermaid estiver vazio → erro
O arquivo é salvo em DIAGRAM_OUT_DIR (dentro de PROJECT_ROOT)
Caminho de saída: a imagem é salva em PROJECT_ROOT/DIAGRAM_OUT_DIR/<filename>.png (diretório de saída padrão: ./diagrams/).
Nome do arquivo: derivado de title (sanitizado para ser seguro para o sistema de arquivos). Se title estiver ausente, um nome padrão é usado.
Conflitos de nome: se <filename>.png já existir, ele é sobrescrito.

Exemplo

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

Requisitos

Python 3.10+ (recomendado)
Acesso à internet (para Kroki e para GitHub ao usar a fonte github)

Estrutura do projeto

.
├── 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

Para detalhes de arquitetura, veja: ARCHITECTURE.md

Docker (opcional)

Compile e execute com Docker (exemplo):

# 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

Instalação e configuração

1) Clone o repositório

git clone <REPO_URL>
cd <REPO_DIR>

2) Crie um venv + instale as dependências

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]

Isso instala as dependências de execução e extras de desenvolvimento (testes).

3) Configuração (Variáveis de Ambiente)

Você pode definir variáveis de ambiente no seu shell OU no arquivo de configuração do cliente MCP que inicia o servidor.

Obrigatórias / Recomendadas

Variável	Descrição	Usada por
`PROJECT_ROOT`	Raiz do projeto local que o servidor tem permissão de acessar (limite de segurança)	`local_source`
`KROKI_BASE_URL`	ex.: `https://kroki.io`	`render_mermaid`
`KROKI_TIMEOUT`	Tempo limite de requisição do Kroki	`render_mermaid`
`DIAGRAM_OUT_DIR`	Onde salvar os PNGs (deve estar dentro de `PROJECT_ROOT`)	`render_mermaid`
`MAX_FILE_CHARS`	Máximo de caracteres a ler de um arquivo (evita leituras enormes)	`read_file`

Opcionais

Variável	Descrição	Usada por
`HTTP_VERIFY`	Verificar certificados SSL (conforme necessário)	`server`
`GITHUB_TOKEN`	Recomendado para evitar limites de taxa do GitHub; se definido, adiciona um cabeçalho `Authorization`	`src/clients/github/client.py`

Exemplo (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

Exemplo (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) Execute o servidor (stdio)

python src/server/server.py

Nome do servidor: `mermaid-mcp`

Conecte um cliente MCP (exemplo: Claude Desktop)

Qualquer cliente MCP que possa iniciar um servidor stdio local pode usar este projeto. Abaixo está um exemplo de configuração para Claude Desktop.

1) Localize a configuração do Claude Desktop

Claude Desktop armazena as definições do servidor MCP em um arquivo de configuração JSON.

Locais comuns:

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

Se o arquivo não existir ainda, crie-o.

2) Adicione este servidor a `claude_desktop_config.json`

Exemplo (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) Reinicie o Claude Desktop

Após salvar o arquivo de configuração, feche completamente o Claude Desktop e abra-o novamente para que o servidor seja carregado.

4) Verifique se as ferramentas estão disponíveis

Abra o Claude Desktop e verifique se as ferramentas do servidor aparecem (ex.: list_files, read_file, render_mermaid).

Usando o prompt canônico

Este projeto inclui um prompt de sistema canônico usado para gerar diagramas Mermaid de forma consistente e orientada a ferramentas. O prompt está registrado no servidor MCP sob o nome generate_mermaid_canonical e é definido em src/prompts/mermaid_prompt.py.

Duas maneiras comuns de usá-lo:

Prompts com suporte do cliente (recomendado): Se o seu cliente MCP suporta prompts do lado do servidor, selecione o servidor mermaid-mcp, escolha o prompt chamado generate_mermaid_canonical na lista de prompts e execute-o como o sistema/instrução do agente antes de invocar as ferramentas. Usar o prompt registrado no servidor garante que os agentes sempre recebam o texto mais recente do prompt.
Copiar e colar: Se o seu cliente não suporta prompts do lado do servidor, abra src/prompts/mermaid_prompt.py, copie o texto do prompt e cole-o na mensagem de sistema do agente ou salve-o localmente como um preset. Tenha em mente que você precisará atualizar sua cópia local quando o prompt do repositório mudar.

Notas:

O prompt canônico impõe uso estrito de ferramentas e exige que o recurso de estilo canônico mermaid://styles/blue-flowchart seja lido e incorporado inalterado nos diagramas gerados.
O prompt espera que o agente siga o pipeline: list_files → read_file → gerar Mermaid → render_mermaid.

Testes

Execute a suíte de testes:

pytest -q

Exemplo de ponta a ponta:

Este é um fluxo completo e realista que demonstra o pipeline pretendido: list_files → read_file → gerar Mermaid → render_mermaid.

Etapa 1 — Liste arquivos de um repositório GitHub

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

Etapa 2 — Escolha um pequeno conjunto de arquivos importantes (5–12)

Exemplo de seleção (você escolhe com base no que o repositório contém):

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

Etapa 3 — Leia os arquivos escolhidos

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

Etapa 4 — Gere Mermaid a partir do que você leu

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

Etapa 5 — Renderize Mermaid para PNG

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

Segurança e comportamento previsível

Para segurança e comportamento previsível, veja: Limites de segurança

Solução de problemas

"Missing repo_url for github source" → você esqueceu repo_url com source="github"
"Missing file path" → você chamou read_file sem path
"Access outside project root is not allowed" → tentativa de ler fora de PROJECT_ROOT
"DIAGRAM_OUT_DIR must be within PROJECT_ROOT" → o diretório de saída não está dentro de PROJECT_ROOT

Trabalho futuro (fontes adicionais)

Em seguida, planejamos suportar mais fontes de entrada além de pastas locais e GitHub, para que o servidor possa gerar diagramas Mermaid a partir de outros provedores de código e conteúdo (ex.: GitLab, Bitbucket, Azure DevOps Repos, bem como arquivos ZIP ou arquivos únicos via URL).

Isso será construído sobre uma abstração unificada Source: cada nova fonte implementará o mesmo contrato (list_files e read_file), enquanto as ferramentas permanecem inalteradas—estender o suporte exigirá apenas adicionar uma nova implementação de fonte e registrá-la na fábrica.

mermaid-mcp-server Public

Documentação

mermaid-mcp — um servidor MCP para diagramar qualquer projeto (Local/GitHub → Mermaid → PNG)

Por que este servidor

Recursos principais

Ele expõe três ferramentas:

1) list_files

Parâmetros

Exemplo (local)

Exemplo (github)

2) read_file

Parâmetros

Exemplo (local)

Exemplo (github)

3) render_mermaid

Parâmetros

Retornos

Comportamento

Exemplo

Requisitos

Estrutura do projeto

Docker (opcional)

Instalação e configuração

1) Clone o repositório

2) Crie um venv + instale as dependências

Windows (PowerShell):

Windows (CMD):

macOS/Linux:

3) Configuração (Variáveis de Ambiente)

Obrigatórias / Recomendadas

Opcionais

4) Execute o servidor (stdio)

Nome do servidor: mermaid-mcp

Conecte um cliente MCP (exemplo: Claude Desktop)

1) Localize a configuração do Claude Desktop

2) Adicione este servidor a claude_desktop_config.json

3) Reinicie o Claude Desktop

4) Verifique se as ferramentas estão disponíveis

Usando o prompt canônico

Testes

Exemplo de ponta a ponta:

Etapa 1 — Liste arquivos de um repositório GitHub

Etapa 2 — Escolha um pequeno conjunto de arquivos importantes (5–12)

Etapa 3 — Leia os arquivos escolhidos

Etapa 4 — Gere Mermaid a partir do que você leu

Etapa 5 — Renderize Mermaid para PNG

Segurança e comportamento previsível

Solução de problemas

Trabalho futuro (fontes adicionais)

1) `list_files`

2) `read_file`

3) `render_mermaid`

Nome do servidor: `mermaid-mcp`

2) Adicione este servidor a `claude_desktop_config.json`