Mermaid Lint MCP

中文版本 | English

A powerful tool for validating Mermaid diagrams with both CLI and MCP server capabilities. Perfect for developers, technical writers, and AI assistants who work with Mermaid diagrams.

🚀 Quick Start

Install and Use Immediately

# Validate a Mermaid file
npx mermaid-lint-mcp lint diagram.mmd

# Validate Mermaid code directly
npx mermaid-lint-mcp lint --code "graph TD; A-->B"

# Start MCP server for AI assistants
npx mermaid-lint-mcp server

# Get help
npx mermaid-lint-mcp --help

No installation required! The tool will be downloaded automatically on first use.

🎯 Use Cases

For Developers

• Pre-commit validation: Ensure all Mermaid diagrams in your codebase are valid
• CI/CD integration: Add diagram validation to your build pipeline
• Documentation quality: Catch syntax errors before publishing docs

For Technical Writers

• Content validation: Verify diagrams render correctly before publication
• Error debugging: Get clear error messages for syntax issues

For AI Assistants

• Real-time validation: Validate generated diagrams instantly
• MCP integration: Seamless integration with Claude Code, Cursor, Trae, and other AI tools
• Automated workflows: Enable AI to self-validate diagram outputs

📋 Features

• ✅ Fast Validation: Optimized for speed with browser reuse and local libraries
• ✅ Multiple Formats: Support for all Mermaid diagram types
• ✅ Dual Interface: Both CLI tool and MCP server in one package
• ✅ Error Details: Clear error messages with line numbers and suggestions
• ✅ Timeout Control: Configurable validation timeouts
• ✅ Zero Config: Works out of the box

🛠️ Installation Options

Option 1: Use with npx (Recommended)

No installation needed - just use npx mermaid-lint-mcp directly.

Option 2: Global Installation

npm install -g mermaid-lint-mcp
# Then use: mermaid-lint-mcp

Option 3: Local Project Installation

npm install mermaid-lint-mcp
# Then use: npx mermaid-lint-mcp

📖 Usage Guide

CLI Commands

Validate Diagrams

# Validate a file
npx mermaid-lint-mcp lint diagram.mmd
npx mermaid-lint-mcp diagram.mmd  # 'lint' is default

# Validate code string
npx mermaid-lint-mcp lint --code "graph TD; A-->B"

# With custom timeout (5 seconds)
npx mermaid-lint-mcp lint --timeout 5000 diagram.mmd

# Validate with file option
npx mermaid-lint-mcp lint --file diagram.mmd

Start MCP Server

# Start server for AI assistant integration
npx mermaid-lint-mcp server

Get Help

npx mermaid-lint-mcp --help     # Show all commands
npx mermaid-lint-mcp --version  # Show version

MCP Server Integration

For Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "mermaid-lint": {
      "command": "npx",
      "args": ["mermaid-lint-mcp", "server"]
    }
  }
}

For Other MCP Clients, the setup is similar to above, please refer to the official documentation

📊 Supported Diagram Types

Type	Syntax	Example
Flowchart	flowchart TD	Decision trees, processes
Sequence	sequenceDiagram	API interactions, workflows
Class	classDiagram	Object relationships
State	stateDiagram-v2	State machines
ER	erDiagram	Database schemas
Gantt	gantt	Project timelines
Pie	pie	Data visualization
Journey	journey	User experiences
Git Graph	gitgraph	Version control flows
...	...	...

🔧 Configuration

Validation Options

interface ValidationOptions {
  timeout?: number;  // Timeout in milliseconds (default: 5000)
}

Environment Variables

# Set default timeout
export MERMAID_TIMEOUT=10000

# Enable debug logging
export DEBUG=mermaid-lint-mcp

🔍 Example Outputs

Valid Diagram

{
  "isValid": true,
  "error": null,
  "diagramType": "flowchart"
}

Invalid Diagram

{
  "isValid": false,
  "error": "Parse error on line 8: ...> C E --> F[End ---------------------^ Expecting 'SQE', 'DOUBLECIRCLEEND', 'PE', '-)', 'STADIUMEND', 'SUBROUTINEEND', 'PIPE', 'CYLINDEREND', 'DIAMOND_STOP', 'TAGEND', 'TRAPEND', 'INVTRAPEND', 'UNICODE_TEXT', 'TEXT', 'TAGSTART', got '1'",
  "diagramType": "flowchart"
}

CLI Output

$ npx mermaid-lint-mcp lint --code "graph TD; A-->B"
🔍 Validating Mermaid diagram...
✅ Diagram is valid!
📊 Diagram type: flowchart

🚨 Common Issues & Solutions

Issue: "Command not found"

Solution: Use npx mermaid-lint-mcp instead of mermaid-lint-mcp

Issue: Validation timeout

Solution: Increase timeout with --timeout 10000

Issue: Permission denied

Solution: Run with appropriate permissions or use npx

📝 License

MIT License - see LICENSE file for details.

🙋‍♂️ Support

• 📖 Documentation
• 🐛 Report Issues
• 💬 Discussions

🔗 Related Tools

• Mermaid - Create diagrams with text
• Mermaid Live Editor - Online diagram editor
• Model Context Protocol - AI integration standard