diagrams-mcp

Description

diagrams-mcp is an MCP that allows for the automatic generation of diagrams from text or JSON structures. It currently supports:

• Class diagrams (UML)

• Entity-relationship (ER) diagrams

• Generation via natural language

• SVG export using Mermaid

• Integration designed for MCP agents

The goal is to allow an agent or user to describe a system and obtain the corresponding diagram without writing Mermaid manually.

Related MCP server: AI Charts

Installation

1. Clone the repository

git clone https://github.com/nacho-mazzoni/diagrams-mcp.git
cd diagrams-mcp

1. Install dependencies

npm install

1. Install Mermaid CLI (if not already installed)

npm install -g @mermaid-js/mermaid-cli

1. Verify installation

mmdc -h

Usage

This MCP is designed to work alongside an agent. The recommended workflow is:

1. Ask the agent to analyze the project code.

2. Request that the agent generate a JSON with:

   • Detected classes

   • Entities

   • Attributes

   • Relationships

   • Changes made

3. Pass that JSON directly to the MCP.

4. The MCP automatically generates the corresponding diagram.

This allows the diagram to be built from the actual state of the code or the changes introduced by the agent, without the need to manually write Mermaid.

The MCP accepts:

• Structured JSON generated by the agent

• Natural language describing the model

• Partial data to update existing diagrams

Integration with an agent

A user can integrate diagrams-mcp into their agent by following this workflow:

1. The user asks the agent to analyze the code or describe a system.

2. The agent generates a structured JSON with entities, classes, attributes, and relationships.

3. The agent sends that JSON to the MCP.

4. diagrams-mcp generates the diagram automatically.

5. The agent returns the generated SVG to the user.

Conceptual workflow:

Usuario -> Agente -> JSON -> diagrams-mcp -> SVG -> Usuario

This allows the diagram to reflect the actual state of the code or the changes made by the agent.

Example of JSON generated by an agent

{
  "entities": [
    { "name": "Usuario", "attributes": ["id", "nombre"] },
    { "name": "Pedido", "attributes": ["id", "fecha"] }
  ],
  "relations": [
    {
      "from": "Usuario",
      "to": "Pedido",
      "fromCard": "1",
      "toCard": "1..*",
      "label": "realiza"
    }
  ]
}

That JSON is passed directly to the MCP to generate the diagram.

Project structure

diagrams-mcp
│
├── tools
│   ├── classDiagram.js
│   └── erDiagram.js
│
├── parsers
│   ├── textToClass.js
│   └── textToER.js
│
├── index.js
└── package.json

Project goal

• Integration with MCP agents

• Automatic diagram generation during development

• Support for natural language

• Future extension to more diagram types

Current status

• ER diagrams with cardinality and PK and FK keys

• UML class diagrams

• Parser from text

• SVG export

Clarifications

The MCP also supports the definition of entities with attributes, primary keys (PK), and foreign keys (FK) using text blocks separated by blank lines, allowing for the generation of complete ER diagrams from structured descriptions.