mermaid-mcp-server Public

Servidor MCP para generar diagramas Mermaid a partir de proyectos (locales/GitHub) y renderizarlos mediante Kroki.

Documentación

mermaid-mcp — un servidor MCP para diagramar cualquier proyecto (Local/GitHub → Mermaid → PNG)

Mermaid MCP Server es un servidor MCP que ayuda a los agentes a convertir grandes bases de código (carpetas locales o repositorios de GitHub) en diagramas Mermaid y renderizarlos como imágenes PNG mediante Kroki, permitiendo una comprensión rápida y confiable de la estructura y el flujo de un proyecto.

Por qué este servidor

Al trabajar con una base de código nueva, es fácil perder tiempo saltando entre carpetas y archivos. Este servidor proporciona un flujo de trabajo limpio y basado en herramientas para que los agentes descubran, lean y visualicen un proyecto, sin adivinar rutas ni inventar estructuras.

Características clave

Fuentes locales + GitHub: analiza una carpeta de proyecto local o un repositorio remoto.
Pipeline amigable para agentes: list_files → read_file → generar Mermaid → render_mermaid.
Límite seguro de acceso local: las lecturas locales están restringidas a PROJECT_ROOT.
Límites configurables: controla el tamaño máximo de archivo (MAX_FILE_CHARS) y el directorio de salida (DIAGRAM_OUT_DIR).
Salida portátil: los diagramas renderizados se devuelven como contenido de imagen y también se guardan como archivos PNG.

Expone tres herramientas:

Herramienta	Descripción
`list_files`	Lista archivos de una carpeta local o un repositorio de GitHub (soporta filtrado por raíz + glob).
`read_file`	Lee el contenido de archivos (local o GitHub) con una longitud máxima configurable.
`render_mermaid`	Renderiza texto Mermaid mediante Kroki y devuelve `ImageContent` (también lo guarda en disco).

1) `list_files`

Devuelve una lista de archivos para una fuente determinada (local / github) con filtrado por root + glob.

Parámetros

source: "local" o "github"
root: predeterminado "."
glob: predeterminado "**/*"
repo_url: requerido cuando source="github"
ref: predeterminado "main"
recursive: predeterminado true

Ejemplo (local)

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

Ejemplo (github)

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

2) `read_file`

Lee el contenido de archivos (local o GitHub) con un límite de longitud.

Parámetros

source: "local" o "github"
path: requerido
repo_url: requerido cuando source="github"
ref: predeterminado "main"
max_chars: predeterminado MAX_FILE_CHARS

Ejemplo (local)

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

Ejemplo (github)

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

3) `render_mermaid`

Acepta texto Mermaid, lo renderiza a PNG mediante Kroki, devuelve ImageContent y guarda el archivo en disco.

Parámetros

mermaid: requerido (cadena) — el texto fuente del diagrama Mermaid
title: opcional (cadena) — se usa para derivar el nombre del archivo de salida (se sanitizará)

Devuelve

ImageContent que contiene los bytes del PNG renderizado
También escribe el archivo PNG en PROJECT_ROOT/DIAGRAM_OUT_DIR/<filename>.png

Comportamiento

Si mermaid está vacío → error
El archivo se guarda en DIAGRAM_OUT_DIR (dentro de PROJECT_ROOT)
Ruta de salida: la imagen se guarda en PROJECT_ROOT/DIAGRAM_OUT_DIR/<filename>.png (directorio de salida predeterminado: ./diagrams/).
Nombre de archivo: derivado de title (sanitizado para ser seguro en el sistema de archivos). Si falta title, se usa un nombre predeterminado.
Colisiones de nombre: si <filename>.png ya existe, se sobrescribe.

Ejemplo

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

Requisitos

Python 3.10+ (recomendado)
Acceso a Internet (para Kroki, y para GitHub cuando se usa la fuente github)

Estructura del proyecto

.
├── 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 detalles de arquitectura, consulta: ARCHITECTURE.md

Docker (opcional)

Compila y ejecuta con Docker (ejemplo):

# 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

Instalación y configuración

1) Clonar el repositorio

git clone <REPO_URL>
cd <REPO_DIR>

2) Crear un entorno virtual + instalar dependencias

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]

Esto instala las dependencias de ejecución y las extras de desarrollo (pruebas).

3) Configuración (variables de entorno)

Puedes establecer variables de entorno en tu shell O en la configuración del cliente MCP que inicia el servidor.

Requeridas / Recomendadas

Variable	Descripción	Usada por
`PROJECT_ROOT`	Raíz del proyecto local a la que el servidor puede acceder (límite de seguridad)	`local_source`
`KROKI_BASE_URL`	p. ej. `https://kroki.io`	`render_mermaid`
`KROKI_TIMEOUT`	Tiempo de espera de la solicitud a Kroki	`render_mermaid`
`DIAGRAM_OUT_DIR`	Dónde guardar los PNG (debe estar dentro de `PROJECT_ROOT`)	`render_mermaid`
`MAX_FILE_CHARS`	Máximo de caracteres para leer de un archivo (evita lecturas enormes)	`read_file`

Opcionales

Variable	Descripción	Usada por
`HTTP_VERIFY`	Verificar certificados SSL (según sea necesario)	`server`
`GITHUB_TOKEN`	Recomendado para evitar límites de tasa de GitHub; si se establece, agrega un encabezado `Authorization`	`src/clients/github/client.py`

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

Ejemplo (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) Ejecutar el servidor (stdio)

python src/server/server.py

Nombre del servidor: `mermaid-mcp`

Conectar un cliente MCP (ejemplo: Claude Desktop)

Cualquier cliente MCP que pueda iniciar un servidor stdio local puede usar este proyecto. A continuación se muestra una configuración de ejemplo para Claude Desktop.

1) Localizar la configuración de Claude Desktop

Claude Desktop almacena las definiciones de los servidores MCP en un archivo de configuración JSON.

Ubicaciones comunes:

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

Si el archivo aún no existe, créalo.

2) Agregar este servidor a `claude_desktop_config.json`

Ejemplo (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) Reiniciar Claude Desktop

Después de guardar el archivo de configuración, cierra completamente Claude Desktop y vuelve a abrirlo para que el servidor se cargue.

4) Verificar que las herramientas estén disponibles

Abre Claude Desktop y verifica que aparezcan las herramientas del servidor (p. ej. list_files, read_file, render_mermaid).

Uso del prompt canónico

Este proyecto incluye un prompt de sistema canónico utilizado para generar diagramas Mermaid de manera consistente y orientada a herramientas. El prompt está registrado en el servidor MCP con el nombre generate_mermaid_canonical y se define en src/prompts/mermaid_prompt.py.

Dos formas comunes de usarlo:

Prompts compatibles con el cliente (recomendado): si tu cliente MCP admite prompts del lado del servidor, selecciona el servidor mermaid-mcp, elige el prompt llamado generate_mermaid_canonical de la lista de prompts y ejecútalo como sistema/instrucción del agente antes de invocar las herramientas. Usar el prompt registrado en el servidor garantiza que los agentes siempre obtengan el texto más reciente del prompt.
Copiar y pegar: si tu cliente no admite prompts del lado del servidor, abre src/prompts/mermaid_prompt.py, copia el texto del prompt y pégalo en el mensaje de sistema del agente o guárdalo localmente como ajuste preestablecido. Ten en cuenta que deberás actualizar tu copia local cuando cambie el prompt del repositorio.

Notas:

El prompt canónico impone un uso estricto de las herramientas y requiere que el recurso de estilo canónico mermaid://styles/blue-flowchart se lea e incruste sin cambios en los diagramas generados.
El prompt espera que el agente siga el pipeline: list_files → read_file → generar Mermaid → render_mermaid.

Pruebas

Ejecuta la suite de pruebas:

pytest -q

Ejemplo de extremo a extremo:

Este es un flujo completo y realista que demuestra el pipeline previsto: list_files → read_file → generar Mermaid → render_mermaid.

Paso 1 — Listar archivos de un repositorio de GitHub

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

Paso 2 — Elegir un conjunto pequeño de archivos importantes (5–12)

Selección de ejemplo (tú eliges según lo que contenga el repositorio):

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

Paso 3 — Leer los archivos elegidos

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

Paso 4 — Generar Mermaid a partir de lo leído

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

Paso 5 — Renderizar Mermaid a PNG

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

Seguridad y comportamiento predecible

Para seguridad y comportamiento predecible, consulta: Límites de seguridad

Solución de problemas

"Missing repo_url for github source" → olvidaste repo_url con source="github"
"Missing file path" → llamaste a read_file sin path
"Access outside project root is not allowed" → se intentó leer fuera de PROJECT_ROOT
"DIAGRAM_OUT_DIR must be within PROJECT_ROOT" → el directorio de salida no está dentro de PROJECT_ROOT

Trabajo futuro (fuentes adicionales)

A continuación, planeamos admitir más fuentes de entrada además de las carpetas locales y GitHub, para que el servidor pueda generar diagramas Mermaid a partir de otros hosts de código y proveedores de contenido (p. ej., GitLab, Bitbucket, Azure DevOps Repos, así como archivos ZIP o archivos individuales mediante URL).

Esto se basará en una abstracción unificada Source: cada nueva fuente implementará el mismo contrato (list_files y read_file), mientras que las herramientas permanecerán sin cambios: ampliar la compatibilidad solo requerirá agregar una nueva implementación de fuente y registrarla en la fábrica.

mermaid-mcp-server Public

Documentación

mermaid-mcp — un servidor MCP para diagramar cualquier proyecto (Local/GitHub → Mermaid → PNG)

Por qué este servidor

Características clave

Expone tres herramientas:

1) list_files

Parámetros

Ejemplo (local)

Ejemplo (github)

2) read_file

Parámetros

Ejemplo (local)

Ejemplo (github)

3) render_mermaid

Parámetros

Devuelve

Comportamiento

Ejemplo

Requisitos

Estructura del proyecto

Docker (opcional)

Instalación y configuración

1) Clonar el repositorio

2) Crear un entorno virtual + instalar dependencias

Windows (PowerShell):

Windows (CMD):

macOS/Linux:

3) Configuración (variables de entorno)

Requeridas / Recomendadas

Opcionales

4) Ejecutar el servidor (stdio)

Nombre del servidor: mermaid-mcp

Conectar un cliente MCP (ejemplo: Claude Desktop)

1) Localizar la configuración de Claude Desktop

2) Agregar este servidor a claude_desktop_config.json

3) Reiniciar Claude Desktop

4) Verificar que las herramientas estén disponibles

Uso del prompt canónico

Pruebas

Ejemplo de extremo a extremo:

Paso 1 — Listar archivos de un repositorio de GitHub

Paso 2 — Elegir un conjunto pequeño de archivos importantes (5–12)

Paso 3 — Leer los archivos elegidos

Paso 4 — Generar Mermaid a partir de lo leído

Paso 5 — Renderizar Mermaid a PNG

Seguridad y comportamiento predecible

Solución de problemas

Trabajo futuro (fuentes adicionales)

1) `list_files`

2) `read_file`

3) `render_mermaid`

Nombre del servidor: `mermaid-mcp`

2) Agregar este servidor a `claude_desktop_config.json`