# Diagrams.so

> Diagrams.so is a freemium MCP server for cloud and infrastructure. MCP server that generates and edits AWS, Azure, GCP and Kubernetes diagrams as draw.io. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Freemium
- **Platforms:** CLI, API, Web
- **Website:** https://diagrams.so/developers
- **Repository:** https://github.com/redhold/diagrams-mcp-app-core
- **MCP Registry name:** io.github.RedHold/diagrams-so-mcp
- **Categories:** cloud and infrastructure, design and media
- **Listing updated:** 2026-11-16

## About

The server is a thin stdio client over the Diagrams.so REST API, exposing 23 tools to Claude Desktop, Claude Code and Cursor. You describe an architecture in plain language, and the assistant generates a diagram, reports design warnings with a score, and exports it. Follow-up requests such as adding a CloudFront distribution or fixing a no-encryption warning create new versions.

A setup quirk is worth knowing: instead of copying an API key you run an npx login command once and approve in a browser, or set an email so the first tool call sends a one-time sign-in code. The README says every plan has unlimited diagrams and edits with only a per-minute rate limit. The Paid plan adds draw.io export and removes the watermark; the Free plan returns a watermarked SVG.

It needs Node 18 or later.

## Features

- **Prompt to diagram:** Creates cloud architecture diagrams from a text description.
- **Design warnings:** Returns Well-Architected warnings and a score.
- **Warning fixes:** Resolves one flagged warning at a time.
- **Natural-language edits:** Applies changes as new versions.
- **draw.io export:** Paid plan saves real editable draw.io XML.
- **Browser login:** Approve once in a browser instead of copying a key.

## Good for

- Draft an AWS three-tier architecture from a sentence
- Fix a design warning and check the new score
- Add a component to an existing diagram
- Export a diagram as SVG for a README

## Install

### Claude Code (Terminal)

```sh
claude mcp add diagrams-so-mcp --env DIAGRAMS_API_KEY='<DIAGRAMS_API_KEY>' -- npx -y @diagrams-so/mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "diagrams-so-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@diagrams-so/mcp"
      ],
      "env": {
        "DIAGRAMS_API_KEY": "<DIAGRAMS_API_KEY>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "diagrams-so-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@diagrams-so/mcp"
      ],
      "env": {
        "DIAGRAMS_API_KEY": "<DIAGRAMS_API_KEY>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "diagrams-so-mcp": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@diagrams-so/mcp"
      ],
      "env": {
        "DIAGRAMS_API_KEY": "<DIAGRAMS_API_KEY>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "diagrams-so-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@diagrams-so/mcp"
      ],
      "env": {
        "DIAGRAMS_API_KEY": "<DIAGRAMS_API_KEY>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "diagrams-so-mcp": {
      "command": "npx",
      "args": [
        "-y",
        "@diagrams-so/mcp"
      ],
      "env": {
        "DIAGRAMS_API_KEY": "<DIAGRAMS_API_KEY>"
      }
    }
  }
}
```

## Tools

- `generate_diagram`: Creates a diagram from a prompt and returns warnings and a score.
- `edit_diagram`: Applies a natural-language change as a new version.
- `fix_warning`: Resolves one Well-Architected warning.
- `relayout_diagram`: Re-arranges the layout using AI.
- `import_diagram`: Imports an existing diagram.
- `get_warnings`: Lists design warnings for a diagram.
- `export_diagram`: Exports a diagram, for example as draw.io or SVG.

## FAQ

### Do I need an API key?

Not necessarily. Run npx @diagrams-so/mcp login and approve in the browser, or set DIAGRAMS_API_KEY.

### What does the free plan give?

Diagrams as a watermarked image; the editable draw.io file needs the Paid plan.

### Which clouds are covered?

AWS, Azure, GCP and Kubernetes per the registry entry.

### Is there a web alternative?

Yes, diagrams.so/create offers the same thing without MCP.

### Is Diagrams.so free?

Diagrams.so has a free plan, with paid plans for more usage or features.

### How do I add Diagrams.so to Claude Code?

Run this command in your terminal: claude mcp add diagrams-so-mcp --env DIAGRAMS_API_KEY='<DIAGRAMS_API_KEY>' -- npx -y @diagrams-so/mcp

### What are the best alternatives to Diagrams.so?

The closest alternatives to Diagrams.so are HyperFrames by HeyGen, ffmpeg-skill, AvatarSay — Fictional Character & Talking Video MCP, ChartAnt and VfxSmith.

## Alternatives

- [HyperFrames by HeyGen](https://ai-powered.com/mcp/hyperframes-by-heygen): HyperFrames by HeyGen is a freemium MCP server for design and media.
- [ffmpeg-skill](https://ai-powered.com/mcp/ffmpeg-skill): ffmpeg-skill is an open-source MCP server for design and media.
- [AvatarSay — Fictional Character & Talking Video MCP](https://ai-powered.com/mcp/avatarsay-fictional-character-and-talking-video-mcp): AvatarSay — Fictional Character & Talking Video MCP is a freemium MCP server for design and media.
- [ChartAnt](https://ai-powered.com/mcp/chartant): ChartAnt is a freemium MCP server for design and media.
- [VfxSmith](https://ai-powered.com/mcp/vfxsmith): VfxSmith is a freemium MCP server for design and media.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.
- [Hourlore](https://ai-powered.com/mcp/hourlore): Hourlore is a freemium MCP server for design and media.
- [CalderFlow](https://ai-powered.com/mcp/calderflow): CalderFlow is a free MCP server for design and media.

---
Source: https://ai-powered.com/mcp/diagrams-so
