Diagrams.so

by redhold

Not rated
GitHub

About

Generate and edit cloud architecture diagrams as native draw.io files, from a prompt or from Terraform

Details

Author
redhold
Categories
Developer Tools

Setup

Install Diagrams.so in your MCP client (Claude Desktop, Cursor, Windsurf, and others).

Repository: https://github.com/redhold/diagrams-mcp-app-core

Follow the installation instructions in the repository README, then restart your MCP client.

TheDiagrams.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.

NeedsNode ≥ 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/mcpif 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 withDIAGRAMS_API_BASE.

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

Add the server to your client config (below) withDIAGRAMS_LOGIN_EMAILset 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, pressApprove, and ask again. Nothing to install or type.

loginonly connects the machine. It never generates anything itself, so there is nogeneratecommand to type in a terminal. You write the promptin your assistant's normal chat boxand it calls the tools for you.

MCP servers load at startup, so restart your client after adding it.Then run/mcpand confirmdiagrams-soshows 23 tools.

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 callsgenerate_diagram, thenget_warnings, thenexport_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.

Each reply carries the credit cost and your remaining balance. Generating, editing, fixing and re-laying-out spend credits; reading, warnings andevery exportare free.

The.drawiofile the assistant saves opens atapp.diagrams.netor in the desktop app, fully editable — it is real draw.io XML, not a picture.

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

Reads and exports are free;generate/edit/fix/relayoutcost credits, anddeleteis destructive.relayoutasks forconfirm=truebefore it charges.

Installing the package putsdiagrams-soon your PATH. The longerdiagrams-so-mcpname still works, andnpx @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

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

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 runningnpx @diagrams-so/mcp loginonce, or, withDIAGRAMS_LOGIN_EMAILset, by asking for a diagram and following the link the first tool call gives you (the sign-in code arrives by email). SetDIAGRAMS_API_KEYinstead 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."

Downloaddiagrams-so.mcpbfrom thelatest releaseand 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, seeDeveloping locally.

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

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

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).

# 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 matchpackage.json'sversion(the workflow enforces this). The.mcpbbundle appears on the GitHub Release; manualworkflow_dispatchproduces 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_BASEvariable (non-prod live-smoke target).

- stdout is the MCP channel— the server logs only to stderr.
- Errors come back as clean MCP tool errors carrying the API'scode, HTTP status, andrequest_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_promptemit anotifications/progressevery 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.

Only needed if you are changing the server itself. Users should install from npm, seeQuick 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, no credits # 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

- Code:Apache-2.0. SeeNOTICE.
- Service:this server is a client for the Diagrams.so API. Use of the API is governed by the
Terms of ServiceandAcceptable Use Policy; the code license grants no rights to the API itself.
- Privacy:the server runs locally, connects only toapi.diagrams.so, and contains no telemetry. Credentials fromloginare stored at~/.diagrams-so/credentials.jsonwith owner-only permissions. See the
Privacy Policy.
- Billing:generate, edit, fix, re-layout, and fork operations cost credits; reads and exports are free. Test-mode keys bill your real credit balance.
- 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
security@diagrams.soperSECURITY.md.

This is a web browser that enables your coding agent, such as Claude Code, to visit websites on your behalf and assist you in identifying bugs or creating UI test cases.

Create crafted UI components inspired by the best 21st.dev design engineers.

Bring agent evaluations, observability, and synthetic test set generation directly into your IDE for free with Galileo's new MCP server

An MCP server to help AI assistants to answer questions and generate AccelByte Extend SDK code more effectively .

MCP server for AI Diagram Maker — generate beautiful software engineering diagrams directly inside Cursor, Claude Desktop, Claude Code, or any MCP-compatible AI agent

ALAPI MCP Tools,Call hundreds of API interfaces via MCP

AI-powered SVG animation generator that transforms static files into animated SVG components using the Allyson platform

MCP server that gives AI assistants on-demand access to 1,500+ amCharts docs, ~300 code examples, and 1000+ class API references.

APIMatic MCP Server is used to validate OpenAPI specifications using APIMatic. The server processes OpenAPI files and returns validation summaries by leveraging APIMatic’s API.

One shared context layer for AI agents and humans — live API specs, DB schemas, and versioned contracts across repos so every agent and teammate works from the same source of truth.

Build and deploy full-stack Next.js apps with 98 tools for React, AWS, and MongoDB

No reviews yet — be the first

Sign in to leave a review

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.