Mermaid MCP Server
fay-i/mermaid-mcp
Renderiza diagramas Mermaid para SVG, PDF e decks via MCP
Ver no GitHubServidor 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-mcp1 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
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.
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:
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:
| Parameter | Type | Default | Description |
|---|---|---|---|
code | string | required | Mermaid source code (1-1MB) |
theme | enum | "default" | default, dark, forest, neutral |
background | string | "#ffffff" | CSS background color |
config_json | string | - | Advanced Mermaid configuration |
timeout_ms | number | 30000 | Render timeout (1000-120000ms) |
drop_shadow | boolean | true | Apply drop shadow styling |
google_font | string | "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:
| Parameter | Type | Default | Description |
|---|---|---|---|
diagrams | array | required | 1-100 diagrams with code and optional title |
page_size | enum | "letter" | letter, a4, legal |
orientation | enum | "landscape" | landscape, portrait |
show_titles | boolean | true | Display diagram titles |
margins | object | {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
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 Backend Selection
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
.tmpfiles 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:
Request Lifecycle
Deck Assembly 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
| Code | Description |
|---|---|
INVALID_INPUT | Empty or malformed input |
INPUT_TOO_LARGE | Exceeds 1MB size limit |
PARSE_ERROR | Mermaid syntax error |
RENDER_TIMEOUT | Exceeded timeout budget |
RENDER_FAILED | Browser/Puppeteer error |
PDF_GENERATION_FAILED | PDF conversion error |
STORAGE_ERROR | Storage backend failure |
Requirements
- Node.js 24+
- Docker 24+ (for containerized deployment)
- Chromium (bundled in Docker image)
Documentation
- Architecture Overview - Detailed system architecture
- MCP Specification - Model Context Protocol docs
- Mermaid Documentation - Mermaid diagram syntax
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:
- Follow TDD practices (tests before implementation)
- Run
npm run qualitybefore every commit - One PR per user story
- No skips, ignores, or bypasses in tests or linting
- See AGENTS.md for AI agent guidelines
Security issues? Please report them privately — see our Security Policy.