convez.ai
MCP ServerIntegração & APIsIntermediário
fay-i

Mermaid MCP Server

fay-i/mermaid-mcp

Renderiza diagramas Mermaid para SVG, PDF e decks via MCP

Ver no GitHub
InicialPluginScore · de 0 a 100

Servidor Model Context Protocol para renderizar diagramas Mermaid em SVG, PDF e apresentações multi-página. Integra-se com Claude Code, Cursor e outros workflows MCP, convertendo código Mermaid em artefatos duráveis com suporte a temas, fontes customizáveis e armazenamento local ou S3.

Instalação

$npx convez-ai fay-i/mermaid-mcp

1 comando no terminal: detecta o formato do repositório (marketplace ou plugin avulso) e instala via Claude Code. Requer Node 18+ e o Claude Code instalado.

Métricas

Estrelas
1
Forks
0
Acompanhando
0
Saúde
87%
Último commit
há 2 semanas
Versão
—
Issues abertas
69
Contribuidores
3

Casos de uso

  • Gerar diagramas arquiteturais em fluxos de trabalho de IA
  • Criar apresentações multi-página com múltiplos diagramas
  • Integrar renderização de diagramas em aplicações MCP
  • Documentar fluxos e estruturas de forma automatizada

Veredito

MCP server bem estruturado e focado que resolve um problema específico: renderizar diagramas Mermaid como artefatos persistentes em vez de blocos de texto. Implementação sólida com suporte a múltiplos formatos e backends de armazenamento; recomendado para quem integra Claude/Cursor em pipelines de documentação.

README

A tradução para o português deste README ainda está na fila.

Mermaid MCP Server

Mermaid MCP Server is a TypeScript Model Context Protocol server for rendering Mermaid diagrams from MCP clients and AI coding workflows. It turns Mermaid source into SVG, PDF, and multi-page deck artifacts using Puppeteer, Mermaid CLI, and pdf-lib, with configurable themes, fonts, storage, and download URLs.

Use it when Claude Code, Codex, Cursor, or another MCP-capable workflow needs diagrams that are rendered as durable files instead of pasted source blocks. The server is intentionally focused: accept Mermaid code, render it consistently, and return an artifact reference your client can open, share, or attach to documentation.

High-Level Architecture

Features

  • MCP server for Mermaid rendering: Exposes diagram tools over the Model Context Protocol
  • High-quality rendering: Puppeteer + Mermaid CLI with Google Fonts and drop shadow support
  • Multiple output formats: SVG and PDF with configurable themes (default, dark, forest, neutral)
  • Deck artifacts: Combine multiple diagrams into multi-page PDF presentations
  • Flexible storage: Local filesystem or S3/MinIO with automatic backend detection
  • Docker ready: Volume mount support for persistent artifact storage
  • No telemetry: Runs as your local/server-side MCP process and does not add hidden tracking

Quick Start

Install from npm

# Install globally
npm install -g @fay-i/mermaid-mcp

# Run the MCP server with a data directory
mermaid-mcp ./data/artifacts

# Show help
mermaid-mcp --help

The server requires a data directory argument where generated SVG and PDF files will be stored. The directory will be created if it doesn't exist.

Use from an MCP client

Configure your MCP client to launch the mermaid-mcp binary and pass an artifact directory:

{
  "mcpServers": {
    "mermaid-mcp": {
      "command": "mermaid-mcp",
      "args": ["/absolute/path/to/mermaid-artifacts"]
    }
  }
}

Or run the published package without a global install:

{
  "mcpServers": {
    "mermaid-mcp": {
      "command": "npx",
      "args": ["-y", "@fay-i/mermaid-mcp", "/absolute/path/to/mermaid-artifacts"]
    }
  }
}

Docker Compose (Recommended)

# Clone repository
git clone https://github.com/fay-i/mermaid-mcp.git
cd mermaid-mcp

# Create local storage directory
mkdir -p ./data/artifacts

# Start with local storage (default)
docker-compose up -d

# Verify server is running
curl http://localhost:8000/health

Local Development

# Install dependencies
npm install

# Build the project
npm run build

# Run with a data directory
node dist/index.js ./data/artifacts

Configuration

Local Storage (Default)

Local storage is configured via the required command-line argument:

mermaid-mcp /path/to/data/directory

Artifacts are stored as:

/path/to/data/directory/{session-uuid}/{artifact-uuid}.svg
/path/to/data/directory/{session-uuid}/{artifact-uuid}.pdf

S3 Storage

For S3/MinIO storage, set STORAGE_TYPE=s3 and provide credentials:

# S3 storage settings
STORAGE_TYPE=s3
S3_ENDPOINT=https://s3.amazonaws.com   # S3/MinIO endpoint URL
S3_BUCKET=my-bucket                    # S3 bucket name
AWS_ACCESS_KEY_ID=...                  # AWS access key
AWS_SECRET_ACCESS_KEY=...              # AWS secret key
AWS_REGION=us-east-1                   # AWS region (default: us-east-1)

When using S3, no data directory argument is needed:

STORAGE_TYPE=s3 S3_BUCKET=my-bucket ... mermaid-mcp

Docker Compose Configuration

Local Storage (Default)

services:
  mermaid-mcp:
    build: .
    volumes:
      - ./data/artifacts:/app/data/artifacts

S3 Storage

services:
  mermaid-mcp:
    build: .
    environment:
      - STORAGE_TYPE=s3
      - MERMAID_S3_ENDPOINT=https://s3.amazonaws.com
      - MERMAID_S3_BUCKET=my-bucket
      - MERMAID_S3_ACCESS_KEY=${AWS_ACCESS_KEY_ID}
      - MERMAID_S3_SECRET_KEY=${AWS_SECRET_ACCESS_KEY}
      - AWS_REGION=us-east-1

Local MinIO for Testing

# Start with MinIO included
docker-compose --profile with-s3 up -d

# Configure MCP server to use MinIO
export STORAGE_TYPE=s3
export MERMAID_S3_ENDPOINT=http://localhost:9000
export MERMAID_S3_BUCKET=mermaid
export MERMAID_S3_ACCESS_KEY=minioadmin
export MERMAID_S3_SECRET_KEY=minioadmin

MCP Tools

The server exposes four tools via the Model Context Protocol:

Tools and Inputs

healthcheck

Verify server health and connectivity.

{
  "echo": "test"
}

Response:

{
  "ok": true,
  "status": "healthy",
  "version": "0.1.0",
  "timestamp": "2026-01-07T12:00:00.000Z",
  "echo": "test"
}

mermaid_to_svg

Render a Mermaid diagram to SVG format.

Parameters:

ParameterTypeDefaultDescription
codestringrequiredMermaid source code (1-1MB)
themeenum"default"default, dark, forest, neutral
backgroundstring"#ffffff"CSS background color
config_jsonstring-Advanced Mermaid configuration
timeout_msnumber30000Render timeout (1000-120000ms)
drop_shadowbooleantrueApply drop shadow styling
google_fontstring"Source Code Pro"Custom Google Font

Example:

{
  "code": "flowchart LR\n    A[Start] --> B[End]",
  "theme": "default",
  "drop_shadow": true
}

Response (with storage):

{
  "ok": true,
  "request_id": "550e8400-e29b-41d4-a716-446655440000",
  "artifact_id": "7f3d2c1b-4a5e-6f7d-8c9b-0a1b2c3d4e5f",
  "download_url": "file://data/artifacts/session-uuid/artifact-uuid.svg",
  "content_type": "image/svg+xml",
  "size_bytes": 12345,
  "storage_type": "local"
}

mermaid_to_pdf

Render a Mermaid diagram to PDF format. Same parameters as mermaid_to_svg.

Timeout Budget:

  • SVG rendering: 80% of timeout_ms
  • PDF generation: 20% of timeout_ms
{
  "code": "sequenceDiagram\n    Alice->>Bob: Hello",
  "theme": "neutral"
}

mermaid_to_deck

Combine multiple Mermaid diagrams into a multi-page PDF presentation.

Additional Parameters:

ParameterTypeDefaultDescription
diagramsarrayrequired1-100 diagrams with code and optional title
page_sizeenum"letter"letter, a4, legal
orientationenum"landscape"landscape, portrait
show_titlesbooleantrueDisplay diagram titles
marginsobject{top: 36, ...}Page margins in points

Example:

{
  "diagrams": [
    {"code": "flowchart LR\n    A-->B", "title": "Architecture"},
    {"code": "sequenceDiagram\n    A->>B: Request", "title": "Sequence"}
  ],
  "page_size": "letter",
  "orientation": "landscape"
}

Rendering Pipeline

Rendering Sequence

Post-Processing Features

Drop Shadow Filter: Adds subtle depth to diagram elements for better visual appearance.

Google Font Injection: Embeds custom fonts for consistent typography across different viewing environments.

GitHub Light Theme: Default theme uses GitHub-inspired colors for a clean, professional look.

Storage System

The server uses a pluggable storage backend architecture:

Storage Class Diagram

Storage Backend Selection

Storage Factory

Storage Behavior

Local Storage

  • Path Structure: {LOCAL_STORAGE_PATH}/{session_id}/{artifact_id}.{ext}
  • URL Format: file://{HOST_STORAGE_PATH}/{session_id}/{artifact_id}.{ext}
  • Persistence: Artifacts persist indefinitely (manual cleanup required)
  • Atomic Writes: Temp file + rename pattern prevents partial files
  • Startup Cleanup: Orphaned .tmp files removed on server start

S3 Storage

  • Key Format: {artifact_id}.{ext} (flat structure, no session prefix)
  • URL Format: Presigned HTTPS URLs with configurable expiration
  • Compatibility: Works with AWS S3, MinIO, and other S3-compatible services
  • Backward Compatible: All existing S3 deployments continue to work unchanged

Troubleshooting

"Permission denied" on startup

Problem: Container cannot write to mounted volume.

Solution:

# Fix directory permissions on host
chmod 755 ./data/artifacts

# Or run container with matching UID/GID
docker run --user $(id -u):$(id -g) ...

"file:// URL not accessible"

Problem: File URLs only work on the same machine as the storage.

Solution:

# Option 1: Use HTTP URLs via CDN proxy
export LOCAL_URL_SCHEME=http
export CDN_HOST=mermaid-svc
export CDN_PORT=3001

# Option 2: Ensure HOST_STORAGE_PATH matches actual host mount point
export HOST_STORAGE_PATH=/absolute/path/on/host

"Configuration error: ambiguous storage"

Problem: Auto-detection failed because both local path and S3 credentials are configured.

Solution:

# Explicitly choose storage backend
export STORAGE_TYPE=local  # or STORAGE_TYPE=s3

Disk full errors

Problem: Local storage ran out of disk space.

Solution:

# Check disk usage
df -h /app/data/artifacts

# Remove old artifacts manually
find /app/data/artifacts -name "*.svg" -mtime +30 -delete

S3 connection errors

Problem: Cannot connect to S3/MinIO endpoint.

Solution:

# Verify S3 credentials
aws s3 ls s3://${MERMAID_S3_BUCKET} --endpoint-url=${MERMAID_S3_ENDPOINT}

# Check network connectivity
curl -v ${MERMAID_S3_ENDPOINT}

# Verify environment variables are set correctly
env | grep MERMAID_S3

Development

Running Tests

# Run all quality checks
npm run quality

# Run unit tests only
npm run test

# Run integration tests only
npm run test:integration

# Type checking
npm run typecheck

# Linting
npm run lint

# Format check
npm run format:check

Clean Slate Protocol

Before every commit/push, run the full quality gate from a clean state:

# Clean build artifacts
npm run clean

# Fresh dependency install
rm -rf node_modules && npm install

# Run all quality checks
npm run quality

Architecture

The server follows a modular architecture with clear separation of concerns:

High-Level Architecture

Request Lifecycle

Tool Request Lifecycle

Deck Assembly Pipeline

Deck Pipeline

Source Code Structure

src/
├── index.ts              # MCP server entry point
├── version.ts            # Version constant
├── tools/                # Tool implementations
│   ├── healthcheck.ts
│   ├── mermaid-to-svg.ts
│   ├── mermaid-to-pdf.ts
│   └── mermaid-to-deck.ts
├── renderer/             # Rendering engine
│   ├── browser.ts        # Puppeteer lifecycle
│   ├── render.ts         # Mermaid → SVG
│   └── deck-assembler.ts # PDF merging (pdf-lib)
├── storage/              # Storage backends
│   ├── factory.ts        # Backend factory
│   ├── local-backend.ts  # Local filesystem
│   └── s3-backend.ts     # S3/MinIO
└── schemas/              # Zod validation schemas
    ├── mermaid-to-svg.ts
    ├── mermaid-to-pdf.ts
    └── mermaid-to-deck.ts

Error Codes

CodeDescription
INVALID_INPUTEmpty or malformed input
INPUT_TOO_LARGEExceeds 1MB size limit
PARSE_ERRORMermaid syntax error
RENDER_TIMEOUTExceeded timeout budget
RENDER_FAILEDBrowser/Puppeteer error
PDF_GENERATION_FAILEDPDF conversion error
STORAGE_ERRORStorage backend failure

Requirements

  • Node.js 24+
  • Docker 24+ (for containerized deployment)
  • Chromium (bundled in Docker image)

Documentation

License

MIT - See LICENSE file for details.

Contributing

Contributions are welcome! Please read CONTRIBUTING.md for the development workflow, quality gate, and branch conventions, and our Code of Conduct.

In short:

  1. Follow TDD practices (tests before implementation)
  2. Run npm run quality before every commit
  3. One PR per user story
  4. No skips, ignores, or bypasses in tests or linting
  5. See AGENTS.md for AI agent guidelines

Security issues? Please report them privately — see our Security Policy.

Ver o original no GitHub

Bom para

Relacionados