mermaider

The mermaider MCP server provides a dedicated tool called validate_syntax that uses a headless browser context to verify Mermaid diagram syntax across all diagram types. It relies on puppeteer-core to connect to an installed browser (e.g., Chrome/Chromium or Firefox) and reuses a single browser page for subsequent syntax checks to minimize startup latency. This approach avoids spawning a new browser process for each request, enabling faster and more deterministic validation results than some alternatives that invoke the mmdc CLI for every call.

To use the server, run the MCP client configuration that points to mermaider. The typical invocation runs the mermaider package via npx, with a configuration object that specifies browser settings (if needed). The primary capability is the validate_syntax tool, which takes Mermaid diagram code and returns syntax validation feedback. If the diagram is valid, you’ll receive a success response; if there are syntax errors, you’ll get a detailed error message indicating where the problem occurs. This setup is designed to be responsive for interactive LLM-assisted diagram generation workflows inside editors like VSCode or in Cursor/Windsuf-style environments.

Prerequisites

• Node.js installed on the host system (recommended: latest LTS)
• npm (comes with Node.js) or corepack if you prefer pnpm/yarn
• A compatible browser installed locally (Chrome/Chromium or Firefox) for Puppeteer to connect to

Installation steps

1. Verify Node.js and npm are available

node -v
npm -v

2. Install and run mermaider via npx (the MCP client will pass a configuration file or inline JSON)

npx -y @vtomilin/mermaider '{"executablePath": "/path/to/browser", "browser": "firefox"}'

3. If using a specific browser, ensure the configuration points to the installed executable in the JSON config (as per the examples in the README). For VSCode or other MCP clients, you can embed the same JSON in the server config, for example:

{
  "mcpServers": {
    "mermaider": {
      "command": "npx",
      "args": ["-y", "@vtomilin/mermaider", "/path/to/Firefox.json"]
    }
  }
}

4. Optional: create a dedicated environment or container that has Node.js and Puppeteer-compatible browser installed to ensure consistent behavior across environments.

Notes and tips:

• The server expects a browser to be available locally; Puppeteer will download its own browser by default if not provided, which can be large and introduce variability. Prefer supplying an existing browser via the configuration to keep startup predictable.
• Use a secondary or dedicated browser for mermaider to avoid impacting your primary browser sessions.
• If you see issues with certain Mermaid features, ensure your browser version is compatible with mermaid-js/mermaid and Puppeteer.
• The mermaider tool is designed for low-latency syntax checking by reusing a single browser page; if you need to reset state, restarting the MCP server will recreate the browser context.
• When integrating with editors or IDEs, you can feed code blocks or prompt outputs directly to mermaider for immediate syntax feedback.