How do I install Diagrams.so?

Copy the stdio config for Cursor, Claude Desktop, Claude Code, or VS Code on this page. It uses the publisher's install, not a PlugMCP proxy.

Does Diagrams.so need an API key?

The publisher lists these environment variables: DIAGRAMS_API_KEY, DIAGRAMS_API_BASE, DIAGRAMS_API_TIMEOUT_MS.

What transport does Diagrams.so use?

Diagrams.so runs locally over stdio.

When was Diagrams.so last checked?

Last checked 2026-11-09. Generate and edit AWS, Azure, GCP and Kubernetes architecture diagrams as editable draw.io files.

Diagrams.so MCP server

Power your agent

Add this server

The publisher's own command. Not a PlugMCP endpoint.

Add to Cursor Add to VS Code Run on PlugMCP

Host a copy with our keys and logs.

Local command

npx -y @diagrams-so/[email protected]

Credentials from the publisher

DIAGRAMS_API_KEY — Diagrams.so API key (dgz_live_... or dgz_test_...). Optional since 1.4.0: run `npx @diagrams-so/mcp login` once instead. Or create a key at https://diagrams.so under Settings then API Keys.
DIAGRAMS_API_BASE — API base URL. Defaults to production; override only for a local or self-hosted API.
DIAGRAMS_API_TIMEOUT_MS — Per-request timeout in milliseconds for slow generate/edit/fix calls.

Claude Code has no install link for a local command. Copy the command below and run it in a terminal.

shClaude Code

1DIAGRAMS_API_KEY=<secret> DIAGRAMS_API_BASE=<value> DIAGRAMS_API_TIMEOUT_MS=<value> claude mcp add io.github.redhold-diagrams-so-mcp -- npx -y @diagrams-so/mcp@1.4.7

Run in a terminal.

jsonClaude Desktop

1{2  "mcpServers": {3    "io.github.redhold-diagrams-so-mcp": {4      "command": "npx",5      "args": [6        "-y",7        "@diagrams-so/[email protected]"8      ],9      "env": {10        "DIAGRAMS_API_KEY": "<secret>",11        "DIAGRAMS_API_BASE": "<value>",12        "DIAGRAMS_API_TIMEOUT_MS": "<value>"13      }14    }15  }16}

claude_desktop_config.json

Local · npmPublisher installStep-by-step: add this in Claude

Remote URL or a command on your machine? How the two installs differ

Run on PlugMCP

Host a copy with our keys and logs.

A new server you create. It is not this listing's official endpoint. Use the publisher install when you want their URL and their credentials.

Launch

Server facts

Local

Transport: stdio
Version

Tools

No tool list yet. Remote servers get one after the first health check.

FAQ

Questions

@diagrams-so/mcp

The Diagrams.so MCP server — generate, edit, and manage cloud architecture diagrams from any MCP client (Claude Desktop, Claude Code, Cursor). It's a thin stdio client over the public Diagrams.so API (/api/v2); every tool is one REST call.

Quick start

Needs Node ≥ 18. No API key to copy: you connect by approving in a browser.

# 1. add the server to Claude Code
claude mcp add diagrams-so -- npx -y @diagrams-so/mcp

# 2. connect this machine (a browser opens, press Approve)
npx @diagrams-so/mcp login

Restart your client, then ask: "Generate an AWS 3-tier web app diagram and show me the warnings." Run /mcp if you want to confirm all 23 tools registered first.

Using it a lot? Install once and the command gets shorter:

npm i -g @diagrams-so/mcp
diagrams-so login

The server talks to production (https://api.diagrams.so/api/v2) by default. Point it at a local or self-hosted API with DIAGRAMS_API_BASE.

Using Claude Desktop or Cursor instead of the CLI? See Add it to your MCP client. Prefer a one-click, no-terminal install? See One-click install (MCPB).

Add the server to your client config (below) with DIAGRAMS_LOGIN_EMAIL set to your email, then just ask for a diagram. Because the machine isn't connected yet, the first tool call emails you a one-time sign-in code and replies with a link. Open it, enter the code, press Approve, and ask again. Nothing to install or type.

Generating a diagram from Claude

login only connects the machine. It never generates anything itself, so there is no generate command to type in a terminal. You write the prompt in your assistant's normal chat box and it calls the tools for you.

Client	Where you type the prompt
Claude Code	the terminal chat, same place you ask anything else
Claude Desktop	the normal message box
Cursor	the chat or composer panel

MCP servers load at startup, so restart your client after adding it. Then run /mcp and confirm diagrams-so shows 23 tools.

Now just ask, in plain English:

Generate an AWS three-tier web app with an ALB, EC2 Auto Scaling and RDS Multi-AZ. Show me the design warnings, then export it as draw.io.

Behind that one sentence the assistant calls generate_diagram, then get_warnings, then export_diagram. You never name a tool or write JSON.

More things worth asking, once you have a diagram:

The warnings mention no encryption in transit. Fix that one and show me the new score.

Add a CloudFront distribution in front of the ALB.

Re-export it as SVG so I can drop it in the README.

Every plan has unlimited diagrams and edits. Nothing is metered; there is only a per-minute rate limit. The Paid plan adds no watermark and draw.io export. Free diagrams can be private.

On the Paid plan the .drawio file the assistant saves opens at app.diagrams.net or in the desktop app, fully editable: it is real draw.io XML, not a picture. On the Free plan the tools return a watermarked image (SVG) instead, and say so; the editable draw.io file needs the Paid plan.

Prefer not to use an assistant at all? diagrams.so/create has the same thing as a web page: type the prompt in the box. No install, no login, no MCP.

Tools (23)

Create & change (mutating)

Tool	What it does
`generate_diagram`	Create a diagram from a prompt → id + warnings + score + draw.io XML (Paid) or a watermarked image link (Free)
`edit_diagram`	Apply a natural-language change (new version)
`fix_warning`	Resolve one Well-Architected warning
`relayout_diagram`	AI re-arrange the layout (async; asks for `confirm=true`)
`import_diagram`	Import existing draw.io XML as a new diagram
`update_diagram`	Rename / change visibility / replace XML
`revert_diagram`	Revert to an earlier version
`delete_diagram`	Soft-delete a diagram (destructive)
`fork_template`	Copy a public/library diagram into your account (private)

Read

Tool	What it does
`get_diagram`	Fetch a diagram's score + XML (Paid) or a watermarked image link (Free)
`list_diagrams`	List your diagrams (cursor-paginated)
`get_warnings`	Well-Architected findings for a diagram
`export_diagram`	Raw `svg` (every plan; watermarked on Free) or `drawio` (Paid; on Free you get the watermarked SVG)
`list_versions`	Version history (with `is_current`)
`get_version`	A specific version's score + XML (Paid) or a watermarked image link (Free)
`get_relayout_status`	Poll an async re-layout job
`search_gallery`	Search public community + curated library diagrams
`enhance_prompt`	Turn a rough idea into a detailed prompt
`clarify_prompt`	Get clarifying questions for a vague prompt
`get_usage`	Your plan and usage
`get_usage_history`	Past tasks (action, diagram, surface) with filters + a live session tally
`whoami`	Account, plan, scopes, live/test mode
`list_capabilities`	Valid diagram types / providers / export formats

Every tool is unlimited on every plan. delete is destructive, and relayout asks for confirm=true before it replaces the layout.

CLI

Commands

Installing the package puts diagrams-so on your PATH. The longer diagrams-so-mcp name still works, and npx @diagrams-so/mcp <command> works without installing anything.

npm i -g @diagrams-so/mcp

diagrams-so login          # connect this machine (a browser opens, press Approve)
diagrams-so whoami         # which account is this machine connected as
diagrams-so logout         # remove the local credential
diagrams-so install        # print client config to paste

Environment

Var	Required	Default
`DIAGRAMS_API_KEY`	❌	— (CI and headless only; `login` is the normal path)
`DIAGRAMS_API_BASE`	❌	`https://api.diagrams.so/api/v2` (production; override for local/self-hosted)
`DIAGRAMS_API_TIMEOUT_MS`	❌	`450000` (per-request safety-net; sits above the API's full server-side timeout ladder)
`DIAGRAMS_BROWSER`	❌	— (`login` opens your default browser; set e.g. `Google Chrome` when your Diagrams.so session lives in a non-default browser)
`DIAGRAMS_NO_BROWSER`	❌	— (set to any value to stop `login` opening a browser; the URL is always printed)
`DIAGRAMS_NO_AUTO_LOGIN`	❌	— (set to any value to disable in-tool connect; unauthenticated tools then just say to run `login`)
`DIAGRAMS_LOGIN_EMAIL`	❌	— (address for in-tool connect: the one-time sign-in code is emailed there; without it, unauthenticated tools say to run `login` instead of starting a connect)

Add it to your MCP client

The published package runs straight from npm, so there is no path to fill in and no key in the config. Run npx @diagrams-so/mcp install to print these blocks for your client.

Claude Code (CLI)

claude mcp add diagrams-so -- npx -y @diagrams-so/mcp
npx @diagrams-so/mcp login

Claude Desktop / Cursor (`claude_desktop_config.json` / `mcp.json`)

{
  "mcpServers": {
    "diagrams-so": {
      "command": "npx",
      "args": ["-y", "@diagrams-so/mcp"]
      // optional: "env": { "DIAGRAMS_API_BASE": "http://localhost:8000/api/v2" } for a local API
    }
  }
}

Connect either by running npx @diagrams-so/mcp login once, or, with DIAGRAMS_LOGIN_EMAIL set, by asking for a diagram and following the link the first tool call gives you (the sign-in code arrives by email). Set DIAGRAMS_API_KEY instead only for CI and headless machines, where no browser can open.

Restart the client, then ask: "Generate an AWS 3-tier web app diagram and show me the warnings."

One-click install (MCPB)

Download diagrams-so.mcpb from the latest release and drag it into Claude Desktop. No terminal, and it no longer asks for an API key: install it, then connect on first use by clicking the link the first tool call gives you.

Building the bundle yourself is a contributor step, see Developing locally.

Smithery

The server is listed at smithery.ai/servers/diagrams-so/mcp, which installs it for you and lists all 23 tools with their parameters:

npx -y smithery mcp add diagrams-so/mcp

Same package, same login step. It's the MCPB bundle Smithery installs, not the npm package, so the version shown there follows releases rather than npm dist-tags.

Verify it works

DIAGRAMS_API_KEY=dgz_live_your_key node test-smoke.mjs

Runs the full flow (connect → list tools → whoami → generate → warnings → fix → export → error handling).

Continuous integration & releases

Workflow	Trigger	What it does
CI (`ci.yml`)	every push / PR	`npm ci` + `npm run build` on Node 18/20/22, then a free smoke (`scripts/ci-smoke.mjs`) that launches the built server and asserts all 23 tools register. No API calls.
Live smoke (`live-smoke.yml`)	nightly + manual	the full end-to-end flow (`test-smoke.mjs`) against the real API. Calls the real API, so it runs only when the `DIAGRAMS_API_KEY` secret is set.
Release (`release.yml`)	tag `vX.Y.Z`	build → `npm prune --omit=dev` → pack `diagrams-so.mcpb` → attach to a GitHub Release. Publishes to npm too if an `NPM_TOKEN` secret is set.

Cut a release:

# bump "version" in package.json + manifest.json to match, commit, then:
git tag v1.2.0 && git push origin v1.2.0

The tag must match package.json's version (the workflow enforces this). The .mcpb bundle appears on the GitHub Release; manual workflow_dispatch produces it as a downloadable artifact without publishing (handy for testing a bundle).

Repo secrets/variables (optional): DIAGRAMS_API_KEY (live smoke), NPM_TOKEN (npm publish), DIAGRAMS_API_BASE variable (non-prod live-smoke target).

Notes

stdout is the MCP channel — the server logs only to stderr.
Errors come back as clean MCP tool errors carrying the API's code, HTTP status, and request_id.
The server never talks to internal services or the database — only the public /api/v2.
Long-running tools stay alive past client timeouts. generate / edit / fix / relayout / enhance_prompt / clarify_prompt emit a notifications/progress every 10s while running, so MCP clients that reset their request timeout on progress (resetTimeoutOnProgress) won't abort a slow generation at the SDK's 60s default. If your client doesn't reset on progress, raise its per-call timeout for these tools.

Developing locally

Only needed if you are changing the server itself. Users should install from npm, see Quick start.

git clone https://github.com/RedHold/diagrams-mcp-app-core.git
cd diagrams-mcp-app-core
npm install                  # installs deps and builds dist/ via the prepare hook
node scripts/ci-smoke.mjs    # all 23 tools register; no API calls

# point a client at your working copy
claude mcp add diagrams-so-dev -- node "$(pwd)/dist/index.js"

# build the MCPB bundle
npm run build && npx @anthropic-ai/mcpb pack

License and legal

Code: Apache-2.0. See NOTICE.
Service: this server is a client for the Diagrams.so API. Use of the API is governed by the Terms of Service and Acceptable Use Policy; the code license grants no rights to the API itself.
Privacy: the server runs locally, connects only to api.diagrams.so, and contains no telemetry. Credentials from login are stored at ~/.diagrams-so/credentials.json with owner-only permissions. See the Privacy Policy.
Plans: every plan has unlimited diagrams and edits, with a per-minute rate limit. Paid adds no watermark and draw.io export; Free diagrams can be private. Test-mode keys act on your real account.
Trademarks: Diagrams.so and the Diagrams.so logo are trademarks of RedHold LLC. This license does not grant permission to use them, except to accurately describe the package's origin. See the Trademark Policy.
Security: report vulnerabilities to [email protected] per SECURITY.md.

Add this server

Host a copy with our keys and logs.

Server facts

Tools

Questions

How do I install Diagrams.so?

Does Diagrams.so need an API key?

What transport does Diagrams.so use?

When was Diagrams.so last checked?

Documentation

@diagrams-so/mcp

Quick start

Generating a diagram from Claude

Tools (23)

CLI

Commands

Environment

Add it to your MCP client

Claude Code (CLI)

Claude Desktop / Cursor (claude_desktop_config.json / mcp.json)

One-click install (MCPB)

Smithery

Verify it works

Continuous integration & releases

Notes

Developing locally

License and legal

Claude Desktop / Cursor (`claude_desktop_config.json` / `mcp.json`)