Mermaid Server¶

Overview¶

The Mermaid MCP Server provides comprehensive capabilities for creating, editing, and rendering Mermaid diagrams. It supports multiple diagram types including flowcharts, sequence diagrams, Gantt charts, and class diagrams, with structured input options and template systems. The server is powered by FastMCP for enhanced type safety and automatic validation.

Key Features¶

• Multiple Diagram Types: Flowcharts, sequence diagrams, Gantt charts, class diagrams
• Structured Input: Create diagrams from data structures
• Template System: Built-in templates for common diagram types
• Validation: Syntax validation for Mermaid code
• Multiple Output Formats: SVG, PNG, PDF export
• FastMCP Implementation: Modern decorator-based tools with automatic validation

Quick Start¶

Prerequisites¶

Mermaid CLI must be installed:

npm install -g @mermaid-js/mermaid-cli

Installation¶

# Install in development mode
make dev-install

# Or install normally
make install

Running the Server¶

# Start the FastMCP server
make dev

# Or directly
python -m mermaid_server.server_fastmcp

# HTTP bridge for REST API access
make serve-http

Available Tools¶

create_diagram¶

Create and render Mermaid diagrams.

Parameters: - diagram_type (required): Type of diagram ("flowchart", "sequence", "gantt", "class", etc.) - mermaid_code (required): Mermaid syntax code - title: Diagram title - output_format: Output format ("svg", "png", "pdf") - default: "svg" - output_file: Path for output file - theme: Mermaid theme ("default", "dark", "forest", "neutral") - width: Output width in pixels (100-5000, default: 800) - height: Output height in pixels (100-5000, default: 600)

create_flowchart¶

Create flowcharts from structured data.

Parameters: - nodes (required): List of node definitions with id, label, and shape - connections (required): List of connections between nodes - direction: Flow direction ("TD", "TB", "BT", "LR", "RL") - default: "TD" - title: Flowchart title - output_format: Output format - default: "svg" - output_file: Path for output file

create_sequence_diagram¶

Create sequence diagrams.

Parameters: - participants (required): List of participant names - messages (required): List of message definitions - title: Sequence diagram title - output_format: Output format - default: "svg" - output_file: Path for output file

create_gantt_chart¶

Create Gantt charts from task data.

Parameters: - title (required): Chart title - tasks (required): List of task definitions with name, start, duration/end - output_format: Output format - default: "svg" - output_file: Path for output file

validate_mermaid¶

Validate Mermaid syntax.

Parameters: - mermaid_code (required): Mermaid code to validate

get_templates¶

Get diagram templates.

Parameters: - diagram_type: Specific diagram type to get templates for

Configuration¶

MCP Client Configuration¶

{
  "mcpServers": {
    "mermaid-server": {
      "command": "python",
      "args": ["-m", "mermaid_server.server_fastmcp"],
      "cwd": "/path/to/mermaid_server"
    }
  }
}

Examples¶

Create Flowchart from Structure¶

{
  "nodes": [
    {"id": "A", "label": "Start", "shape": "circle"},
    {"id": "B", "label": "Process", "shape": "rect"},
    {"id": "C", "label": "Decision", "shape": "diamond"},
    {"id": "D", "label": "End", "shape": "circle"}
  ],
  "connections": [
    {"from": "A", "to": "B"},
    {"from": "B", "to": "C"},
    {"from": "C", "to": "D", "label": "Yes"},
    {"from": "C", "to": "B", "label": "No"}
  ],
  "direction": "TD",
  "title": "Sample Workflow",
  "output_format": "png"
}

Create Sequence Diagram¶

{
  "participants": ["Client", "Server", "Database"],
  "messages": [
    {"from": "Client", "to": "Server", "message": "Request Data"},
    {"from": "Server", "to": "Database", "message": "Query"},
    {"from": "Database", "to": "Server", "message": "Results", "arrow": "-->"},
    {"from": "Server", "to": "Client", "message": "Response Data", "arrow": "->>"}
  ],
  "title": "API Request Flow",
  "output_format": "svg"
}

Create Gantt Chart¶

{
  "title": "Project Timeline",
  "tasks": [
    {"name": "Research", "start": "2024-01-01", "duration": "10d"},
    {"name": "Design", "start": "2024-01-11", "duration": "5d"},
    {"name": "Development", "start": "2024-01-16", "end": "2024-02-01"},
    {"name": "Testing", "start": "2024-02-01", "duration": "7d"}
  ],
  "output_format": "pdf"
}

Create Custom Diagram¶

{
  "diagram_type": "flowchart",
  "mermaid_code": "flowchart TD\n    A[Start] --> B{Decision}\n    B -->|Yes| C[Action 1]\n    B -->|No| D[Action 2]\n    C --> E[End]\n    D --> E",
  "title": "Decision Process",
  "theme": "dark",
  "output_format": "png",
  "width": 1200,
  "height": 800
}

Validate Mermaid Code¶

{
  "mermaid_code": "flowchart TD\n    A[Start] --> B[End]"
}

Response:

{
  "success": true,
  "valid": true,
  "message": "Mermaid code is valid",
  "diagram_type": "flowchart",
  "complexity": "simple"
}

Integration¶

With MCP Gateway¶

# Start the Mermaid server via HTTP
make serve-http

# Register with MCP Gateway
curl -X POST http://localhost:8000/gateways \
  -H "Content-Type: application/json" \
  -d '{
    "name": "mermaid-server",
    "url": "http://localhost:9000",
    "description": "Mermaid diagram creation and rendering server"
  }'

Programmatic Usage¶

import asyncio
from mcp import ClientSession, StdioServerParameters
from mcp.client.stdio import stdio_client

async def create_mermaid_diagram():
    server_params = StdioServerParameters(
        command="python",
        args=["-m", "mermaid_server.server_fastmcp"]
    )

    async with stdio_client(server_params) as (read, write):
        async with ClientSession(read, write) as session:
            await session.initialize()

            # Create a flowchart
            result = await session.call_tool("create_flowchart", {
                "nodes": [
                    {"id": "start", "label": "Begin", "shape": "circle"},
                    {"id": "process", "label": "Process", "shape": "rect"},
                    {"id": "end", "label": "Finish", "shape": "circle"}
                ],
                "connections": [
                    {"from": "start", "to": "process"},
                    {"from": "process", "to": "end"}
                ],
                "title": "Simple Process"
            })

asyncio.run(create_mermaid_diagram())

Supported Diagram Types¶

Flowcharts¶

• Purpose: Process flows, decision trees, workflows
• Node Shapes: rect, circle, diamond, round
• Directions: TD (Top Down), LR (Left Right), BT (Bottom Top), RL (Right Left)

Sequence Diagrams¶

• Purpose: System interactions, API flows, communication patterns
• Features: Participants, messages, activation boxes, notes
• Arrow Types: ->, →>, -x, –x

Gantt Charts¶

• Purpose: Project timelines, task scheduling, milestone tracking
• Features: Tasks, dependencies, milestones, progress tracking
• Date Formats: YYYY-MM-DD, duration in days/weeks

Class Diagrams¶

• Purpose: Software architecture, object relationships, UML modeling
• Features: Classes, inheritance, associations, methods

State Diagrams¶

• Purpose: State machines, workflow states, system behavior
• Features: States, transitions, conditions, actions

Entity Relationship Diagrams¶

• Purpose: Database design, data modeling, relationships
• Features: Entities, attributes, relationships, cardinality

Pie Charts¶

• Purpose: Data distribution, percentage breakdowns
• Features: Segments, labels, percentages

User Journey Maps¶

• Purpose: User experience flows, customer journeys
• Features: Stages, emotions, touchpoints

Themes and Styling¶

Available Themes¶

• default: Standard Mermaid theme
• dark: Dark mode theme
• forest: Forest green theme
• neutral: Neutral gray theme

Flow Directions¶

• TD/TB: Top Down/Top to Bottom (default)
• BT: Bottom to Top
• RL: Right to Left
• LR: Left to Right

Node Shapes (Flowcharts)¶

• rect: Rectangle (default)
• circle: Circle nodes
• diamond: Diamond decision nodes
• round: Rounded rectangles

Advanced Features¶

Complex Flowchart Creation¶

# Create a complex business process flowchart
nodes = [
    {"id": "start", "label": "Start Process", "shape": "circle"},
    {"id": "input", "label": "Collect Input", "shape": "rect"},
    {"id": "validate", "label": "Validate Data", "shape": "diamond"},
    {"id": "process", "label": "Process Request", "shape": "rect"},
    {"id": "approve", "label": "Requires Approval?", "shape": "diamond"},
    {"id": "review", "label": "Manager Review", "shape": "rect"},
    {"id": "complete", "label": "Complete", "shape": "circle"},
    {"id": "reject", "label": "Reject", "shape": "circle"}
]

connections = [
    {"from": "start", "to": "input"},
    {"from": "input", "to": "validate"},
    {"from": "validate", "to": "process", "label": "Valid"},
    {"from": "validate", "to": "reject", "label": "Invalid"},
    {"from": "process", "to": "approve"},
    {"from": "approve", "to": "review", "label": "Yes"},
    {"from": "approve", "to": "complete", "label": "No"},
    {"from": "review", "to": "complete", "label": "Approved"},
    {"from": "review", "to": "reject", "label": "Denied"}
]

await session.call_tool("create_flowchart", {
    "nodes": nodes,
    "connections": connections,
    "title": "Business Process Workflow",
    "direction": "TD"
})

Multi-format Output Generation¶

# Generate the same diagram in multiple formats
diagram_code = """
flowchart TD
    A[Start] --> B{Decision}
    B -->|Yes| C[Action 1]
    B -->|No| D[Action 2]
    C --> E[End]
    D --> E
"""

formats = ["svg", "png", "pdf"]
for fmt in formats:
    await session.call_tool("create_diagram", {
        "diagram_type": "flowchart",
        "mermaid_code": diagram_code,
        "output_format": fmt,
        "output_file": f"./diagram.{fmt}"
    })

Template-based Diagram Creation¶

# Get available templates
templates = await session.call_tool("get_templates", {
    "diagram_type": "sequence"
})

# Use a template structure
await session.call_tool("create_sequence_diagram", {
    "participants": ["User", "Frontend", "Backend", "Database"],
    "messages": [
        {"from": "User", "to": "Frontend", "message": "Login Request"},
        {"from": "Frontend", "to": "Backend", "message": "Authenticate"},
        {"from": "Backend", "to": "Database", "message": "Verify Credentials"},
        {"from": "Database", "to": "Backend", "message": "User Data"},
        {"from": "Backend", "to": "Frontend", "message": "Auth Token"},
        {"from": "Frontend", "to": "User", "message": "Login Success"}
    ],
    "title": "User Authentication Flow"
})

Use Cases¶

Software Documentation¶

• System architecture diagrams
• API workflow documentation
• Database relationship diagrams

Business Process Modeling¶

• Workflow documentation
• Decision trees
• Process optimization

Project Management¶

• Project timelines
• Task dependencies
• Milestone tracking

Educational Materials¶

• Concept explanations
• Process illustrations
• System overviews

Technical Communication¶

• Code flow documentation
• System integration diagrams
• Troubleshooting guides

Error Handling¶

The server provides comprehensive error handling for:

• Mermaid CLI Installation: Detection and installation guidance
• Syntax Errors: Detailed Mermaid syntax validation
• Rendering Failures: Output format and rendering issues
• File Access: Permission and directory creation errors
• Resource Limits: Large diagram handling and memory management

Performance Considerations¶

• Mermaid CLI must be installed for diagram rendering
• SVG format provides the best quality and scalability
• PNG/PDF formats are useful for embedding in documents
• Large diagrams may require increased width/height limits
• Complex diagrams with many nodes may impact rendering performance