Log inSubmit server
Mermaid Docs logo

Mermaid Docs

Create step-by-step Mermaid diagram walkthroughs with a local viewer and MCP tools for coding agents.

InstallRepositoryWebsite
Full README Compare alternatives Embed widget Claim this listing

Install Mermaid Docs

Pick your client, then add it in one click or paste the config.

STDIONode.js
~/Library/Application Support/Claude/claude_desktop_config.json
claude_desktop_config.json
{
  "mcpServers": {
    "mermaid-docs": {
      "command": "npx",
      "args": [
        "-y",
        "mermaid-docs"
      ]
    }
  }
}

Settings → Developer → Edit Config, merge this into mcpServers, then fully quit and reopen Claude Desktop.

We couldn’t confirm it starts correctly

We ran the install command but it didn't respond within our test window — this can mean a slow first-time install rather than a real problem.

npx -y mermaid-docs

No response to initialize.

This is an experimental automated check and can have false negatives — missing environment variables, a slow cold install, etc. It doesn’t necessarily mean something’s wrong. Last checked 1d ago.

Overview

The mermaid-docs MCP server helps coding agents turn Mermaid diagrams into guided, step-by-step walkthroughs. It works with a Mermaid `.mmd` file and a same-basename Markdown file, using comment markers to associate diagram regions with documented steps. Its tools can write, reorder, and validate steps, then link to the step an agent created. Reach for it when a static diagram needs an ordered explanation that highlights relevant connections and source lines.

Use cases

  • Document an authentication flow as a guided walkthrough
  • Generate step descriptions for an existing Mermaid diagram
  • Reorder walkthrough steps for a clearer reading sequence
  • Validate diagram walkthrough files in continuous integration

Key features

  • Step markers embedded as Mermaid comments
  • Markdown explanations linked to diagram regions
  • Local step-by-step viewer
  • MCP tools for writing, reordering, and validating steps
  • Live updates without restarting the viewer
  • Direct links to agent-created steps

Security & health

What it can reach and how reliably it runs — from our own checks, not the maintainer’s claims.

ActiveLast checked 3d ago

Recent health check succeeded.

Supply-chain signal

No high-severity advisories surfaced by our automated scan.

Critical 0High 0Medium 0Low 0

Scanned 7d ago via OSV.dev · mermaid-docs (npm)

Adoption & maintenance

Factual signals from GitHub, npm, and our automated checks — not a rating.

GitHub stars4Stargazers on the source repository.
npm downloads504Package downloads in the last 30 days.
Last commit7d agoMost recent push to the default branch.
Install checkInconclusiveDidn't respond in our test window — often a slow first install.

How Mermaid Docs works

What the mermaid-docs MCP server does

The mermaid-docs MCP server adds a walkthrough layer to ordinary Mermaid diagrams. A diagram remains a .mmd file that can render in other Mermaid-compatible contexts, while comments identify which lines belong to each documented step. A separate Markdown file with the same basename supplies the explanation for those steps.

The local viewer presents the diagram one step at a time. It highlights the connections associated with the current step, shows the source lines that produce them, and displays the accompanying prose. Content changes in either file appear without restarting the viewer.

How it works

Mark a region in the Mermaid source with matching start and end comments. The marker includes a step identifier, such as request:

text
%% @step:start request
Client[Browser] --> API[API]
%% @step:end request

Add a Markdown section whose heading begins with the same identifier:

markdown
## request - The browser calls the API

A plain GET, no auth yet.

The viewer uses the shared identifier to connect the source region and its explanation. The mermaid-docs MCP server teaches the connected coding agent this format, so the agent can create or revise the walkthrough instead of requiring manual editing for every step.

Setup and configuration

The command shown by the project for opening a folder is:

Terminal
npx mermaid-docs ./docs

Point the command at the folder containing the Mermaid and Markdown files. The repository provides separate documentation for MCP server setup in docs/mcp.md, including the agent setup, and for the viewer and CLI.

For publishing, the documentation includes a GitHub Pages guide.

Tools and capabilities

The mermaid-docs MCP server provides tools that let a coding agent:

  • Write walkthrough steps in the expected file format.
  • Reorder existing steps.
  • Validate the walkthrough.
  • Open or link directly to the step it just wrote.

The viewer dims content outside the active step and follows both the diagram connections and the source lines behind them.

Limitations and notes

The walkthrough metadata is stored as Mermaid comments, which keeps the diagram itself portable. The approach requires the diagram and its same-basename Markdown companion to remain coordinated: step identifiers in the comments must match the identifiers used in the Markdown headings.

The project is designed for local viewing and agent-assisted authoring. Consult the repository's viewer and MCP documentation before relying on a specific client or diagram feature.

The project is licensed under MIT.

Read the full README View source on GitHub

Reviews

No reviews yet — be the first to share how it worked for you.

Frequently Asked Questions about Mermaid Docs

mermaid-docs is an MCP server that connects coding agents to Mermaid diagram and walkthrough files in a local repository. Its main tools let agents write, reorder, and validate walkthrough steps, then provide a link to the step they wrote. It teaches the required format when the agent connects.

Use the repository's MCP setup instructions in `docs/mcp.md`.

Create a Mermaid `.mmd` file and a same-basename Markdown file, then wrap each documented diagram region in matching `@step:start` and `@step:end` comments. Add a Markdown `##` section beginning with the same step ID, and open the folder with `npx mermaid-docs ./docs`.

Yes, the mermaid-docs MCP server provides a validation tool, and the project documents CLI validation for continuous integration.

Related MCP servers

All in Data Visualization All alternatives
Add a badge to your READMEShow it’s listed — live SVG, Markdown or HTML.

AllMCPs Directory Badge

Full Badge Customizer

Showcase your server listing on GitHub or your project documentation. Embed this dynamic SVG badge to highlight official listing status and live engagement.

Badge Style:
Live Dynamic SVG PreviewMermaid Docs AllMCPs Directory Badge
Markdown (GitHub README)
[![AllMCPs](https://allmcps.com/api/badge/mermaid-docs?style=directory)](https://allmcps.com/mcp/mermaid-docs)
HTML Embed
<a href="https://allmcps.com/mcp/mermaid-docs"><img src="https://allmcps.com/api/badge/mermaid-docs?style=directory" alt="Mermaid Docs on AllMCPs" /></a>