/ Directory / Playground / mermaid-skill
← All servers ↗ GitHub
● Community Agents365-ai ⚡ Instant

mermaid-skill

by Agents365-ai · Agents365-ai/mermaid-skill

Generate Mermaid diagrams (.mmd) inside Claude Code and render to PNG/SVG/PDF via mmdc — 10+ diagram types, automatic layout.

A Claude Code skill that handles the full Mermaid loop: writes .mmd source, invokes mmdc to render, and supports the major Mermaid types (flowchart, sequence, class, state, ERD, gantt, git graph, journey, mindmap, C4). No more pasting into Mermaid live editor.

▶ Watch demo 📦 Install 💡 Use Cases

Why use it

Key features

Live Demo

What it looks like in practice

mermaid-skill.replay ▶ ready
0/0

Install

Author repository · Claude Skills documentation

Use Cases

Real-world ways to use mermaid-skill

Draw an architecture diagram for your current project

👤 Devs writing docs, ADRs, or onboarding guides ⏱ ~20 min beginner

When to use: You keep explaining your architecture in Slack and want a picture.

Flow
  1. Describe the system
    Use mermaid-skill. Draw a flowchart of our service: client → API gateway → (auth / orders / payments) → Postgres / Redis / Stripe.✓ Copied
    → .mmd source with meaningful node names, rendered to PNG in docs/
  2. Add details
    Add labels on each edge showing the protocol (HTTPS, gRPC, TCP) and auth type.✓ Copied
    → Updated source and re-render
  3. Commit it
    Commit docs/architecture.mmd and its PNG.✓ Copied
    → git add and commit run

Outcome: A living diagram in the repo, not a stale slide in Confluence.

Pitfalls
  • Diagram becomes a maze of edges — Let Claude use subgraphs and direction hints; don't cram everything on one layer
Combine with: filesystem · git

Produce a sequence diagram while debugging

👤 Engineers tracing a cross-service bug ⏱ ~15 min beginner

When to use: You're trying to understand an async interaction and English isn't cutting it.

Flow
  1. Describe the flow
    Use mermaid-skill. Sequence diagram: browser → SSR → auth service → session store → page render, with failure mode when session is stale.✓ Copied
    → Sequence diagram with the failure annotated
  2. Annotate the bug
    Highlight the line where the bug manifests.✓ Copied
    → Annotated box/note on the offending message

Outcome: A picture you can paste in the bug ticket.

Generate an ERD from your actual database schema

👤 Data engineers, backend devs ⏱ ~20 min intermediate

When to use: You want a visual of your schema for a design review.

Flow
  1. Introspect
    Use mermaid-skill. Read the schema.sql (or query the live DB via postgres MCP) and produce a Mermaid ERD.✓ Copied
    → .mmd ERD with relationships and cardinalities
  2. Trim noise
    Drop audit tables and focus on the core domain entities.✓ Copied
    → Trimmed ERD

Outcome: An accurate ERD without manual drawing.

Pitfalls
  • Cardinalities wrong when inferred — Provide the actual foreign-key definitions; don't let the model guess
Combine with: postgres

Combinations

Pair with other MCPs for X10 leverage

mermaid-skill + filesystem

Keep diagrams alongside the code they describe

For every service in services/, add a docs/architecture.mmd and render it.✓ Copied
mermaid-skill + postgres

Auto-generate ERDs from live databases

Connect to the staging DB and render its schema as a Mermaid ERD.✓ Copied
mermaid-skill + git

Diagram stays versioned with code changes

Commit updated diagrams in the same PR as the code changes they describe.✓ Copied

Tools

What this MCP exposes

ToolInputsWhen to callCost
write_mermaid description, diagram type Any diagram request 0
render_mmdc .mmd path, output format After source is final local mmdc
iterate_diagram current diagram + feedback Reviewer feedback 0

Cost & Limits

What this costs to run

API quota
None
Tokens per call
Small — Mermaid source is compact
Monetary
Free (mmdc is open source)
Tip
For big diagrams, generate subgraphs separately to avoid retrying large rewrites.

Security

Permissions, secrets, blast radius

Credential storage: None
Data egress: None from skill itself

Troubleshooting

Common errors and fixes

mmdc not found

Install globally: npm i -g @mermaid-js/mermaid-cli

Verify: which mmdc
Render fails with syntax error

Mermaid has version-specific syntax; run mmdc --version and match the skill's assumed version

Verify: mmdc --version
Diagram is a mess of crossing edges

Add direction hints (TD/LR), group with subgraphs, or split into multiple diagrams

Alternatives

mermaid-skill vs others

AlternativeWhen to use it insteadTradeoff
PlantUML / draw.ioYou need more control or non-Mermaid syntaxMore setup, different rendering toolchain
paperbanana-skillAcademic publication-quality diagramsHeavier; different aesthetic goals

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills

Continue exploring

Related tools and workflows

Choose another guide for your workflow, or explore a collection.

Browse all topic collections → · See 29 new official additions →