How to Use Claude Code with Mermaid MCP to Auto-Generate Architecture Diagrams

Feb 25, 2026

Purpose

This post demonstrates how to auto-generate system architecture diagrams from your codebase using Claude Code with the Mermaid MCP server.

Environment

Claude Code (latest)
Node.js 18+
@modelcontextprotocol/server-mermaid

The Problem

When I need to document my system architecture, I face a tedious manual process. I either drag boxes around in tools like Lucidchart or Miro for hours, or I write Mermaid syntax by hand. Both approaches are time-consuming and my diagrams quickly become outdated as the codebase evolves.

I need a way to generate architecture diagrams automatically from my actual code structure.

The Solution: Claude Code + Mermaid MCP

The solution combines Claude Code with the Mermaid MCP (Model Context Protocol) server. This setup allows Claude to understand my system structure and generate Mermaid diagrams automatically.

The workflow works like this:

Export your codebase’s dependency data and service structure as JSON
Provide that context to Claude Code
Ask Claude to generate Mermaid or C4 model diagrams
Output the diagrams to tools like Mermaid Live Editor or Miro

I can explain why this works. The Mermaid MCP server extends Claude Code’s capabilities with diagram generation. When I provide structured data about my system, Claude can transform it into visual diagrams without me writing Mermaid syntax manually.

Setup Guide

First, I install the Mermaid MCP server:

npm install -g @modelcontextprotocol/server-mermaid

Then I configure Claude Code to use the MCP server. I edit the Claude Code configuration file:

{
  "mcpServers": {
    "mermaid": {
      "command": "npx",
      "args": ["@modelcontextprotocol/server-mermaid"]
    }
  }
}

Now I verify the installation:

npx @modelcontextprotocol/server-mermaid --version

Extracting System Structure

Before generating diagrams, I need to extract my system structure as JSON. I create a script to analyze my codebase:

const dependencyGraph = {
  services: [
    {
      name: "auth-service",
      type: "microservice",
      dependencies: ["user-db", "redis"]
    },
    {
      name: "api-gateway",
      type: "backend",
      dependencies: ["auth-service", "payment-service"]
    },
    {
      name: "payment-service",
      type: "microservice",
      dependencies: ["payment-db", "stripe-api"]
    },
    {
      name: "user-db",
      type: "database",
      dependencies: []
    },
    {
      name: "payment-db",
      type: "database",
      dependencies: []
    }
  ]
};

console.log(JSON.stringify(dependencyGraph, null, 2));

Run the script:

node export-dependencies.js > dependencies.json

Now I have a structured representation of my system.

Generating Diagrams with Claude Code

With my dependencies exported, I ask Claude Code to generate diagrams.

Flowchart for Service Dependencies

I provide the JSON to Claude Code:

Here's my service structure:

{
  "services": [
    {
      "name": "auth-service",
      "type": "microservice",
      "dependencies": ["user-db", "redis"]
    },
    {
      "name": "api-gateway",
      "type": "backend",
      "dependencies": ["auth-service", "payment-service"]
    },
    {
      "name": "payment-service",
      "type": "microservice",
      "dependencies": ["payment-db", "stripe-api"]
    }
  ]
}

Generate a Mermaid flowchart showing these services and their dependencies.
Use different shapes for services and databases.

Claude Code generates:

graph TD
    APIGateway[API Gateway] --> AuthService[Auth Service]
    APIGateway --> PaymentService[Payment Service]
    AuthService --> UserDB[(User DB)]
    AuthService --> Redis[(Redis)]
    PaymentService --> PaymentDB[(Payment DB)]
    PaymentService --> StripeAPI[Stripe API]

I can copy this Mermaid code to the Mermaid Live Editor to preview and export as PNG or SVG.

Sequence Diagram for OAuth 2 Flow

For complex request flows, I use sequence diagrams. I ask Claude Code:

Generate a Mermaid sequence diagram for OAuth 2 authorization code flow.
Show: User -> Client App -> Auth Server -> Resource Server

Claude Code outputs:

sequenceDiagram
    participant User
    participant Client
    participant AuthServer
    participant ResourceServer

    User->>Client: Click "Login"
    Client->>AuthServer: Redirect to /authorize
    AuthServer->>User: Show login page
    User->>AuthServer: Enter credentials
    AuthServer->>Client: Return auth code
    Client->>AuthServer: Exchange code for token
    AuthServer->>Client: Return access token
    Client->>ResourceServer: API request with token
    ResourceServer->>Client: Return data

This type of diagram is perfect for explaining complex authentication flows or event pipelines.

C4 Context Diagram

For system-level views, I use the C4 model. I provide context about my system:

Generate a C4 model context diagram for this e-commerce system:

System: E-commerce Platform
Users: Customers, Administrators
External Systems: Stripe (payments), SendGrid (emails)

Show the main system, users, and external integrations.

Claude Code generates:

graph LR
    Customer((Customer)) --> Ecommerce[E-commerce Platform]
    Admin((Admin)) --> Ecommerce
    Ecommerce --> Stripe[Stripe Payment API]
    Ecommerce --> SendGrid[SendGrid Email Service]

The C4 model provides four levels of abstraction: Context, Container, Component, and Code. I use the Context level for stakeholder presentations and drill down to Container/Component levels for technical documentation.

Integrating with Miro

For stakeholder reviews, I integrate the generated diagrams with Miro. The workflow:

Generate Mermaid code via Claude Code
Copy to Mermaid Live Editor to preview
Export as SVG from Mermaid Live Editor
Import to Miro using Miro’s image import
Collaborate with stakeholders on the visual board

Miro also supports Mermaid syntax directly in their apps. I can paste the Mermaid code into Miro diagrams without exporting to SVG first.

Troubleshooting

I encountered some issues during setup. Here’s how I resolved them.

Issue: MCP server not found

npx @modelcontextprotocol/server-mermaid --version

# Check Claude Code config
cat ~/.claude/mcp.json

Issue: Diagram renders incorrectly

I simplified complex graphs by breaking them into sub-diagrams. I also validated the Mermaid syntax at https://mermaid.live before assuming the generation was wrong.

Issue: Claude can’t see MCP server

I restarted Claude Code after updating the MCP configuration. I also checked the MCP server logs:

npx @modelcontextprotocol/server-mermaid --log-level=debug

Common Mistakes

I made a few mistakes when getting started:

Providing too much context at once: I tried to dump my entire codebase structure into one prompt. The generated diagrams were unreadable. I learned to start with high-level services and drill down as needed.
Wrong diagram type: I initially used flowcharts for everything. I learned to use flowcharts for dependencies, sequence diagrams for request flows, and C4 diagrams for system-level views.
Not validating generated diagrams: I assumed Claude’s output was correct. I now always verify the diagrams match my actual architecture.
Forgetting to re-export dependencies: After updating my code, I forgot to re-run the export script. The diagrams became outdated. I now make diagram generation part of my documentation workflow.

Why This Matters

This approach saves me hours of manual diagramming. I can generate accurate diagrams in seconds instead of spending hours dragging boxes around in diagramming tools. More importantly, the diagrams reflect my actual code structure, so they stay in sync as my architecture evolves.

The visuals also help me communicate complex flows to stakeholders. I can explain OAuth 2 sequences, event pipelines, or service dependencies with clear diagrams that I can update as the system changes.

Summary

In this post, I showed how to auto-generate architecture diagrams using Claude Code with Mermaid MCP. The key point is to export your system structure as JSON, feed it to Claude Code with clear diagram requirements, and output Mermaid code for visualization. This workflow saves hours of manual diagramming while keeping documentation in sync with actual code.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Mermaid Documentation
👨‍💻 Model Context Protocol (MCP)
👨‍💻 C4 Model
👨‍💻 Mermaid Live Editor
👨‍💻 @modelcontextprotocol/server-mermaid

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!