mermaid-skill MCP — 사용 사례, 설치 & 라이브 데모

왜 쓰나요

핵심 기능

Covers 10+ Mermaid diagram types
Local render via mmdc (PNG / SVG / PDF)
Automatic layout hints to avoid crossing edges
Iterates on diagrams based on feedback
Works inside your repo, diagrams committed alongside code

라이브 데모

실제 사용 모습

mermaid-skill.replay ▶ 준비됨

0/0

설치

클라이언트 선택

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop → Settings → Developer → Edit Config 열기. 저장 후 앱 재시작.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

Cursor는 Claude Desktop과 동일한 mcpServers 스키마 사용. 프로젝트 설정이 전역보다 우선.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

Cline 사이드바의 MCP Servers 아이콘 클릭 후 "Edit Configuration" 선택.

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "mermaid-skill": {
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ],
      "_inferred": true
    }
  }
}

Claude Desktop과 같은 형식. Windsurf 재시작 후 적용.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "mermaid-skill",
      "command": "git",
      "args": [
        "clone",
        "https://github.com/Agents365-ai/mermaid-skill",
        "~/.claude/skills/mermaid-skill"
      ]
    }
  ]
}

Continue는 맵이 아닌 서버 오브젝트 배열 사용.

~/.config/zed/settings.json

{
  "context_servers": {
    "mermaid-skill": {
      "command": {
        "path": "git",
        "args": [
          "clone",
          "https://github.com/Agents365-ai/mermaid-skill",
          "~/.claude/skills/mermaid-skill"
        ]
      }
    }
  }
}

context_servers에 추가. 저장 시 Zed가 핫 리로드.

claude mcp add mermaid-skill -- git clone https://github.com/Agents365-ai/mermaid-skill ~/.claude/skills/mermaid-skill

한 줄 명령. claude mcp list로 확인, claude mcp remove로 제거.

사용 사례

실전 활용법: mermaid-skill

Draw an architecture diagram for your current project

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

언제 쓸까: You keep explaining your architecture in Slack and want a picture.

사전 조건

mmdc installed — npm i -g @mermaid-js/mermaid-cli
Skill installed — git clone https://github.com/Agents365-ai/mermaid-skill ~/.claude/skills/mermaid-skill

흐름

Describe the system

Use mermaid-skill. Draw a flowchart of our service: client → API gateway → (auth / orders / payments) → Postgres / Redis / Stripe.✓ 복사됨

→ .mmd source with meaningful node names, rendered to PNG in docs/
Add details

Add labels on each edge showing the protocol (HTTPS, gRPC, TCP) and auth type.✓ 복사됨

→ Updated source and re-render
Commit it

Commit docs/architecture.mmd and its PNG.✓ 복사됨

→ git add and commit run

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

함정

Diagram becomes a maze of edges — Let Claude use subgraphs and direction hints; don't cram everything on one layer

함께 쓰기: filesystem · git

Produce a sequence diagram while debugging

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

언제 쓸까: You're trying to understand an async interaction and English isn't cutting it.

흐름

Describe the flow

Use mermaid-skill. Sequence diagram: browser → SSR → auth service → session store → page render, with failure mode when session is stale.✓ 복사됨

→ Sequence diagram with the failure annotated
Annotate the bug

Highlight the line where the bug manifests.✓ 복사됨

→ Annotated box/note on the offending message

결과: A picture you can paste in the bug ticket.

Generate an ERD from your actual database schema

👤 Data engineers, backend devs ⏱ ~20 min intermediate

언제 쓸까: You want a visual of your schema for a design review.

흐름

Introspect

Use mermaid-skill. Read the schema.sql (or query the live DB via postgres MCP) and produce a Mermaid ERD.✓ 복사됨

→ .mmd ERD with relationships and cardinalities
Trim noise

Drop audit tables and focus on the core domain entities.✓ 복사됨

→ Trimmed ERD

결과: An accurate ERD without manual drawing.

함정

Cardinalities wrong when inferred — Provide the actual foreign-key definitions; don't let the model guess

함께 쓰기: postgres

조합

다른 MCP와 조합해 10배 효율

mermaid-skill + filesystem

Keep diagrams alongside the code they describe

For every service in services/, add a docs/architecture.mmd and render it.✓ 복사됨

mermaid-skill + postgres

Auto-generate ERDs from live databases

Connect to the staging DB and render its schema as a Mermaid ERD.✓ 복사됨

mermaid-skill + git

Diagram stays versioned with code changes

Commit updated diagrams in the same PR as the code changes they describe.✓ 복사됨

도구

이 MCP가 노출하는 것

도구	입력	언제 호출	비용
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

비용 및 제한

운영 비용

API 쿼터: None
호출당 토큰: Small — Mermaid source is compact
금액: Free (mmdc is open source)
팁: For big diagrams, generate subgraphs separately to avoid retrying large rewrites.

보안

권한, 시크릿, 파급범위

자격 증명 저장: None

데이터 외부 송신: None from skill itself

문제 해결

자주 발생하는 오류와 해결

mmdc not found

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

확인: which mmdc

Render fails with syntax error

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

확인: mmdc --version

Diagram is a mess of crossing edges

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

대안

mermaid-skill 다른 것과 비교

대안	언제 쓰나	단점/장점
PlantUML / draw.io	You need more control or non-Mermaid syntax	More setup, different rendering toolchain
paperbanana-skill	Academic publication-quality diagrams	Heavier; different aesthetic goals

mermaid-skill