# mermaid-docs [Health: Active]

**Category:** 📊 Data Visualization  
**Repository:** https://github.com/bcage29/mermaid-docs  
**GitHub Stars:** 4  
**npm Downloads (last month):** 504  
**Views:** 0  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/mermaid-docs

## Description
Turn Mermaid diagrams into guided, step-by-step walkthroughs - a local viewer plus an MCP server that lets coding agents write the walkthrough for you

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "mermaid-docs": {
    "command": "npx",
    "args": ["-y","mermaid-docs"]
  }
}
```

## Documentation

## 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:

```bash
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.

_Full upstream README: https://allmcps.com/mcp/mermaid-docs/readme_