# Diagrams.so [Health: Active]

**Category:** ☁️ Cloud Platforms  
**Repository:** https://github.com/RedHold/diagrams-mcp-app-core  
**GitHub Stars:** 0  
**npm Downloads (last month):** 1077  
**Views:** 1  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/diagrams-so

## Description
Generate and edit AWS, Azure, GCP and Kubernetes architecture diagrams as editable draw.io files.

## Tools
Capabilities this server exposes over MCP:

- **generate_diagram** — Create a new cloud architecture diagram from a natural-language prompt. Returns the diagram id, Well-Architected warnings and score, and its draw.io XML on the Paid plan (on Free, a link to the watermarked image instead).
- **edit_diagram** — Apply a natural-language change to an existing diagram (e.g. 'add a Redis cache'). Creates a new version and returns the updated XML (Paid plan; Free gets a link to the watermarked image). Confirm with the user before calling: it mutates the diagram.
- **fix_warning** — Resolve a single Well-Architected warning (from get_warnings), leaving the rest of the diagram untouched. Creates a new version.
- **relayout_diagram** — Automatically re-arrange a diagram's layout for readability (async). Starts the job and waits for it to finish, returning the re-laid XML + fresh warnings/score. Requires confirm=true, because it replaces the current layout. If the job is still running when the wait elapses, returns a job_id you can poll with get_relayout_status.
- **import_diagram** — Import an existing draw.io (mxGraphModel/mxfile) XML document as a new diagram in your account. Validated and sanitized. Free (no AI).
- **update_diagram** — Update a diagram's metadata or XML: rename it, change visibility (public/private — paid plans for private), or replace its XML. Pass only the fields you want to change. Free (no AI).
- **delete_diagram** — Delete (soft-delete) a diagram you own. It stops appearing in list_diagrams and can no longer be fetched. Confirm with the user before calling — this is destructive.
- **revert_diagram** — Revert a diagram to an earlier version (from list_versions). Pass either version_id or version_number. Free (no AI).
- **get_diagram** — Fetch a diagram by id. Returns its title, Well-Architected score, and draw.io XML on the Paid plan (on Free, a link to the watermarked image instead).
- **list_diagrams** — List your diagrams (newest first, cursor-paginated). Returns id, title, cloud, type.
- **get_warnings** — List the Well-Architected findings for a diagram (each has type, component, message). Free.
- **export_diagram** — Export a diagram as a raw file: `drawio` (open at app.diagrams.net) or `svg`. Returns the file content directly. `svg` works on every plan; Free-plan images carry a watermark. The editable `drawio` file needs the Paid plan: on Free, asking for `drawio` returns the watermarked SVG instead.
- **list_versions** — List a diagram's version history (ascending; `is_current` marks the live one). Use with revert_diagram / get_version.
- **get_version** — Fetch a specific version's Well-Architected score and XML (XML on the Paid plan; Free gets a link to the watermarked image), e.g. to inspect before reverting. No charge.
- **get_relayout_status** — Check the status of an async re-layout job started by relayout_diagram. Returns pending/done/failed; when done+applied it includes the re-laid XML + fresh warnings/score. Free.
- **search_gallery** — Search public community diagrams and curated library templates to reuse as a starting point. Returns id, title, and source (community/library). Fork one with fork_template.
- **fork_template** — Copy a PUBLIC gallery diagram or curated library template into your own account (private) so you can edit it. Returns the new diagram id.
- **enhance_prompt** — Turn a rough idea into a detailed generation prompt. Free.
- **clarify_prompt** — Get 1–3 clarifying questions (and a suggested diagram type) for a vague prompt, before generating. Free.
- **get_usage** — Show your current plan and usage. Every plan has unlimited diagrams and edits. Free.
- **get_usage_history** — List past tasks (generate/edit/fix/relayout), newest first, with the diagram each one touched and the surface (api/sdk/mcp) that ran it. Use this to check whether a task already ran. Also shows a running tally of tasks performed in THIS session. Free (read-only).
- **whoami** — Show the account, plan, scopes, and live/test mode of the configured API key. Free.
- **list_capabilities** — Discover the valid diagram types, cloud providers, and export formats the API supports — so you pass valid values to generate_diagram / export_diagram. Free.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

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

## Documentation

## What Diagrams.so MCP server does

The Diagrams.so MCP server gives an MCP client access to Diagrams.so's cloud architecture diagram workflow. It can create diagrams for AWS, Azure, GCP, and Kubernetes from natural-language prompts, returning a diagram ID, editable draw.io XML, warnings, and a score. Existing draw.io XML can also be imported, updated, versioned, reverted, copied from public templates, or soft-deleted.

The output is a real draw.io file that can be opened in diagrams.net or its desktop application. Exports are available as raw draw.io or SVG files. SVG export is free on all plans, although the free plan adds a watermark.

## How it works

The package is a thin stdio client for the public Diagrams.so REST API at `/api/v2`; each MCP tool maps to an API request. An assistant can call several tools in sequence from a normal chat request, such as generating a diagram, retrieving its Well-Architected findings, and exporting the result.

Read operations and exports are free. Generating, editing, fixing warnings, and re-layout operations use credits. Re-layout runs asynchronously, with a status tool for polling, and requires confirmation before a charge applies after the first two re-layouts for a diagram. Usage tools expose the current plan, credit estimates, itemized history, and session totals.

## Setup and configuration

The Diagrams.so MCP server requires Node.js 18 or newer. Run it directly with `npx -y @diagrams-so/mcp`, or install the package globally with npm. The normal authentication flow uses `npx @diagrams-so/mcp login`; a browser opens for approval, and no API key needs to be copied. Clients must be restarted after adding the server so their MCP tool lists refresh.

Claude Desktop and Cursor use an MCP configuration that starts the package with `npx`; Claude Code can add it with `claude mcp add`. A one-click MCPB bundle is also available for Claude Desktop. For machines without a browser, set `DIAGRAMS_API_KEY` for CI or other headless environments. `DIAGRAMS_LOGIN_EMAIL` enables an email-based connection flow on the first tool call.

The default API endpoint is `https://api.diagrams.so/api/v2`. Set `DIAGRAMS_API_BASE` to use a local or self-hosted API. Optional settings include `DIAGRAMS_API_TIMEOUT_MS`, `DIAGRAMS_BROWSER`, `DIAGRAMS_NO_BROWSER`, and `DIAGRAMS_NO_AUTO_LOGIN`.

## Tools and capabilities

The Diagrams.so MCP server exposes tools in four broad groups:

- Create and change: generate, edit, fix a warning, re-layout, import, update, revert, delete, and fork a template.
- Read and export: fetch diagrams, list diagrams, inspect warnings, export files, and retrieve version history or a specific version.
- Discovery and prompting: search the public or curated gallery, expand rough prompts, ask clarification questions, and list supported diagram types, providers, and formats.
- Account and billing: inspect identity, plan details, credit estimates, and filtered usage history.

Natural-language edits create new versions, while version tools expose which version is current. The warning tools provide Well-Architected findings and scores for review during design iteration.

_Full upstream README: https://allmcps.com/mcp/diagrams-so/readme_