Quickstart

You just need a free Diagrams.so account. Then pick one of the two ways in below: connect a client (no key to handle), or create an API key for raw HTTP.

1. Get connected

Connect a client (MCP / SDK)
Create an API key (curl / CI)

For using Diagrams.so from Claude, Cursor, or your own code. Connect once, with nothing to copy or paste:

npx @diagrams-so/mcp@latest login

Enter your email, we email you a one-time code, then sign in in the browser that opens, enter the code, and press Approve. The credential is saved to ~/.diagrams-so/credentials.json and shared by the MCP server and both SDKs, so the MCP tools and DiagramsClient() just work from then on. See Authentication for how it works.

Pin @latest so npx doesn’t reuse an older cached client. Clients before the emailed-code login are rejected with an “update your client” message.

For raw HTTP or CI. Sign in at diagrams.so and open Settings → AI Provider → Create key.

The plaintext key is shown once at creation, so store it in a secret manager.
Prefixed dgz_live_ (production) or dgz_test_ (test mode); scopeable, with an optional expiry.

Confirm it works:

curl https://api.diagrams.so/api/v2/me \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY"

A 200 with your account, plan, and scopes means you are set. A 401 means the key is missing, malformed, or revoked.

Never commit a key or paste it into client-side code. Treat it like a password.

2. Generate your first diagram

In Claude / Cursor (MCP)
From the terminal (SDK)
Raw HTTP (API key)

Add the server to your client, restart it, and just ask in plain English:

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

“Generate an AWS 3-tier web app diagram (ALB, EC2 Auto Scaling, RDS Postgres), show the warnings, and export it as draw.io.”

The agent calls generate_diagram → get_warnings → export_diagram for you. Run npx @diagrams-so/mcp@latest install to print ready-to-paste config for Claude Desktop and Cursor.

Uses the login from step 1 (no key to pass):

pip install -U diagrams-so
python3 -c "
import diagrams_so
c = diagrams_so.DiagramsClient()
d = c.generate('A 3-tier web app on AWS: ALB, EC2 Auto Scaling, RDS Postgres', cloud_provider='aws')
print('id:', d['id'], '| warnings:', len(d['warnings']))
open('diagram.drawio', 'w').write(c.export(d['id'], 'drawio'))
print('saved diagram.drawio, open it at https://app.diagrams.net')
"

curl https://api.diagrams.so/api/v2/diagrams \
  -H "Authorization: Bearer dgz_live_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "prompt": "A 3-tier web app on AWS with an ALB, EC2 Auto Scaling, and RDS Postgres",
    "cloud_provider": "aws"
  }'

Generation is AI-backed and can take 30 seconds or more. On a plain curl there is no progress until it completes, so for live progress use POST /diagrams/stream. Edits and fixes typically take 10 to 20 seconds, and re-layout runs as an async job you poll. The SDKs and MCP server default to a 180-second timeout.

The response carries the diagram id, the native draw.io xml (open it at app.diagrams.net), any Well-Architected warnings you can fix, and your credit usage (generating spends credits; reads and exports are free).

3. Iterate

Edit with a prompt

POST /diagrams/{id}/edit, for example “add a CloudFront distribution in front of the ALB”.

Fix a warning

POST /diagrams/{id}/fix applies a recommended change.

Export

GET /diagrams/{id}/export?format=svg returns draw.io or SVG.

Full SDK walkthrough

Every method in the Python and TypeScript SDKs, over the same login.

Getting started

Model Context Protocol (MCP)

SDKs

Guides

Billing

Resources

1. Get connected

2. Generate your first diagram

3. Iterate

Edit with a prompt

Fix a warning

Export

Full SDK walkthrough

​1. Get connected

​2. Generate your first diagram

​3. Iterate

Edit with a prompt

Fix a warning

Export

Full SDK walkthrough

1. Get connected

2. Generate your first diagram

3. Iterate