{
  "markdown": "# @diagrams-so/mcp\n\n[![CI](https://github.com/RedHold/diagrams-mcp-app-core/actions/workflows/ci.yml/badge.svg)](https://github.com/RedHold/diagrams-mcp-app-core/actions/workflows/ci.yml)\n[![Smithery](https://img.shields.io/badge/Smithery-diagrams--so%2Fmcp-orange)](https://smithery.ai/servers/diagrams-so/mcp)\n\nThe **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.\n\n## Quick start\n\nNeeds **Node ≥ 18**. No API key to copy: you connect by approving in a browser.\n\n```bash\n# 1. add the server to Claude Code\nclaude mcp add diagrams-so -- npx -y @diagrams-so/mcp\n\n# 2. connect this machine (a browser opens, press Approve)\nnpx @diagrams-so/mcp login\n```\n\nRestart your client, then ask: *\"Generate an AWS 3-tier web app diagram and show me the warnings.\"*\nRun `/mcp` if you want to confirm all 23 tools registered first.\n\nUsing it a lot? Install once and the command gets shorter:\n\n```bash\nnpm i -g @diagrams-so/mcp\ndiagrams-so login\n```\n\n> The server talks to production (`https://api.diagrams.so/api/v2`) by default. Point it at a\n> local or self-hosted API with `DIAGRAMS_API_BASE`.\n\nUsing Claude Desktop or Cursor instead of the CLI? See [Add it to your MCP client](#add-it-to-your-mcp-client). Prefer a one-click, no-terminal install? See [One-click install (MCPB)](#one-click-install-mcpb).\n\n<details>\n<summary>No terminal at all (Claude Desktop)</summary>\n\nAdd the server to your client config (below) with `DIAGRAMS_LOGIN_EMAIL` set to your email,\nthen just ask for a diagram. Because the machine isn't connected yet, the first tool call\nemails you a one-time sign-in code and replies with a link. Open it, enter the code, press\n**Approve**, and ask again. Nothing to install or type.\n</details>\n\n## Generating a diagram from Claude\n\n`login` only connects the machine. It never generates anything itself, so there is no\n`generate` command to type in a terminal. You write the prompt **in your assistant's normal\nchat box** and it calls the tools for you.\n\n| Client | Where you type the prompt |\n|---|---|\n| Claude Code | the terminal chat, same place you ask anything else |\n| Claude Desktop | the normal message box |\n| Cursor | the chat or composer panel |\n\n**MCP servers load at startup, so restart your client after adding it.** Then run `/mcp` and\nconfirm `diagrams-so` shows 23 tools.\n\nNow just ask, in plain English:\n\n> Generate an AWS three-tier web app with an ALB, EC2 Auto Scaling and RDS Multi-AZ.\n> Show me the design warnings, then export it as draw.io.\n\nBehind that one sentence the assistant calls `generate_diagram`, then `get_warnings`, then\n`export_diagram`. You never name a tool or write JSON.\n\nMore things worth asking, once you have a diagram:\n\n> The warnings mention no encryption in transit. Fix that one and show me the new score.\n\n> Add a CloudFront distribution in front of the ALB.\n\n> Re-export it as SVG so I can drop it in the README.\n\nEach reply carries the credit cost and your remaining balance. Generating, editing, fixing and\nre-laying-out spend credits; reading, warnings and **every export** are free.\n\nThe `.drawio` file the assistant saves opens at [app.diagrams.net](https://app.diagrams.net) or\nin the desktop app, fully editable — it is real draw.io XML, not a picture.\n\n**Prefer not to use an assistant at all?** [diagrams.so/create](https://diagrams.so/create) has\nthe same thing as a web page: type the prompt in the box. No install, no `login`, no MCP.\n\n## Tools (23)\n\n**Create & change (mutating)**\n\n| Tool | What it does | Cost |\n|---|---|---|\n| `generate_diagram` | Create a diagram from a prompt → id + draw.io XML + warnings + score | credits |\n| `edit_diagram` | Apply a natural-language change (new version) | credits |\n| `fix_warning` | Resolve one Well-Architected warning | credits |\n| `relayout_diagram` | AI re-arrange the layout (async; first 2/diagram free, then confirm) | credits* |\n| `import_diagram` | Import existing draw.io XML as a new diagram | free |\n| `update_diagram` | Rename / change visibility / replace XML | free |\n| `revert_diagram` | Revert to an earlier version | free |\n| `delete_diagram` | Soft-delete a diagram (destructive) | free |\n| `fork_template` | Copy a public/library diagram into your account (private) | free |\n\n**Read (free)**\n\n| Tool | What it does |\n|---|---|\n| `get_diagram` | Fetch a diagram's XML + score |\n| `list_diagrams` | List your diagrams (cursor-paginated) |\n| `get_warnings` | Well-Architected findings for a diagram |\n| `export_diagram` | Raw `drawio` or `svg` file (free on every plan; free-plan SVG is watermarked) |\n| `list_versions` | Version history (with `is_current`) |\n| `get_version` | A specific version's XML + score |\n| `get_relayout_status` | Poll an async re-layout job |\n| `search_gallery` | Search public community + curated library diagrams |\n| `enhance_prompt` | Turn a rough idea into a detailed prompt |\n| `clarify_prompt` | Get clarifying questions for a vague prompt |\n| `get_usage` | Plan + credits + cost estimates |\n| `get_usage_history` | Itemized credit ledger per task (action, credits, diagram, surface) with filters + a live session tally |\n| `whoami` | Account, plan, scopes, live/test mode |\n| `list_capabilities` | Valid diagram types / providers / export formats |\n\nReads and exports are free; `generate` / `edit` / `fix` / `relayout` cost credits, and `delete` is destructive. `relayout` asks for `confirm=true` before it charges.\n\n## CLI\n\n### Commands\n\nInstalling the package puts `diagrams-so` on your PATH. The longer\n`diagrams-so-mcp` name still works, and `npx @diagrams-so/mcp <command>` works\nwithout installing anything.\n\n```bash\nnpm i -g @diagrams-so/mcp\n\ndiagrams-so login          # connect this machine (a browser opens, press Approve)\ndiagrams-so whoami         # which account is this machine connected as\ndiagrams-so logout         # remove the local credential\ndiagrams-so install        # print client config to paste\n```\n\n### Environment\n| Var | Required | Default |\n|---|---|---|\n| `DIAGRAMS_API_KEY` | ❌ | — (CI and headless only; `login` is the normal path) |\n| `DIAGRAMS_API_BASE` | ❌ | `https://api.diagrams.so/api/v2` (production; override for local/self-hosted) |\n| `DIAGRAMS_API_TIMEOUT_MS` | ❌ | `450000` (per-request safety-net; sits above the API's full server-side timeout ladder) |\n| `DIAGRAMS_BROWSER` | ❌ | — (`login` opens your default browser; set e.g. `Google Chrome` when your Diagrams.so session lives in a non-default browser) |\n| `DIAGRAMS_NO_BROWSER` | ❌ | — (set to any value to stop `login` opening a browser; the URL is always printed) |\n| `DIAGRAMS_NO_AUTO_LOGIN` | ❌ | — (set to any value to disable in-tool connect; unauthenticated tools then just say to run `login`) |\n| `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) |\n\n## Add it to your MCP client\n\nThe published package runs straight from npm, so there is no path to fill in and no key in the\nconfig. Run `npx @diagrams-so/mcp install` to print these blocks for your client.\n\n### Claude Code (CLI)\n```bash\nclaude mcp add diagrams-so -- npx -y @diagrams-so/mcp\nnpx @diagrams-so/mcp login\n```\n\n### Claude Desktop / Cursor (`claude_desktop_config.json` / `mcp.json`)\n```jsonc\n{\n  \"mcpServers\": {\n    \"diagrams-so\": {\n      \"command\": \"npx\",\n      \"args\": [\"-y\", \"@diagrams-so/mcp\"]\n      // optional: \"env\": { \"DIAGRAMS_API_BASE\": \"http://localhost:8000/api/v2\" } for a local API\n    }\n  }\n}\n```\n\nConnect either by running `npx @diagrams-so/mcp login` once, or, with `DIAGRAMS_LOGIN_EMAIL`\nset, by asking for a diagram and following the link the first tool call gives you (the sign-in\ncode arrives by email). Set `DIAGRAMS_API_KEY` instead only for CI and headless machines,\nwhere no browser can open.\n\nRestart the client, then ask: *\"Generate an AWS 3-tier web app diagram and show me the warnings.\"*\n\n### One-click install (MCPB)\nDownload `diagrams-so.mcpb` from the\n[latest release](https://github.com/RedHold/diagrams-mcp-app-core/releases/latest) and drag it into\nClaude Desktop. No terminal, and it no longer asks for an API key: install it, then connect on first\nuse by clicking the link the first tool call gives you.\n\nBuilding the bundle yourself is a contributor step, see [Developing locally](#developing-locally).\n\n### Smithery\nThe server is listed at [smithery.ai/servers/diagrams-so/mcp](https://smithery.ai/servers/diagrams-so/mcp),\nwhich installs it for you and lists all 23 tools with their parameters:\n\n```bash\nnpx -y smithery mcp add diagrams-so/mcp\n```\n\nSame package, same `login` step. It's the MCPB bundle Smithery installs, not the npm package, so the\nversion shown there follows releases rather than `npm dist-tags`.\n\n## Verify it works\n```bash\nDIAGRAMS_API_KEY=dgz_live_your_key node test-smoke.mjs\n```\nRuns the full flow (connect → list tools → whoami → generate → warnings → fix → export → error handling).\n\n## Continuous integration & releases\n\n| Workflow | Trigger | What it does |\n|---|---|---|\n| **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, no credits.** |\n| **Live smoke** (`live-smoke.yml`) | nightly + manual | the full end-to-end flow (`test-smoke.mjs`) against the real API. **Spends credits** — runs only when the `DIAGRAMS_API_KEY` secret is set. |\n| **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. |\n\n**Cut a release:**\n```bash\n# bump \"version\" in package.json + manifest.json to match, commit, then:\ngit tag v1.2.0 && git push origin v1.2.0\n```\nThe tag must match `package.json`'s `version` (the workflow enforces this). The\n`.mcpb` bundle appears on the GitHub Release; manual `workflow_dispatch` produces\nit as a downloadable artifact without publishing (handy for testing a bundle).\n\n**Repo secrets/variables (optional):** `DIAGRAMS_API_KEY` (live smoke),\n`NPM_TOKEN` (npm publish), `DIAGRAMS_API_BASE` variable (non-prod live-smoke target).\n\n## Notes\n- **stdout is the MCP channel** — the server logs only to stderr.\n- Errors come back as clean MCP tool errors carrying the API's `code`, HTTP status, and `request_id`.\n- The server never talks to internal services or the database — only the public `/api/v2`.\n- **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.\n\n## Developing locally\n\nOnly needed if you are changing the server itself. Users should install from npm, see\n[Quick start](#quick-start).\n\n```bash\ngit clone https://github.com/RedHold/diagrams-mcp-app-core.git\ncd diagrams-mcp-app-core\nnpm install                  # installs deps and builds dist/ via the prepare hook\nnode scripts/ci-smoke.mjs    # all 23 tools register; no API calls, no credits\n\n# point a client at your working copy\nclaude mcp add diagrams-so-dev -- node \"$(pwd)/dist/index.js\"\n\n# build the MCPB bundle\nnpm run build && npx @anthropic-ai/mcpb pack\n```\n\n## License and legal\n\n- **Code:** [Apache-2.0](./LICENSE). See [NOTICE](./NOTICE).\n- **Service:** this server is a client for the Diagrams.so API. Use of the API is governed by the [Terms of Service](https://diagrams.so/policy/terms) and [Acceptable Use Policy](https://diagrams.so/policy/acceptable-use); the code license grants no rights to the API itself.\n- **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](https://diagrams.so/policy/privacy).\n- **Billing:** generate, edit, fix, re-layout, and fork operations cost credits; reads and exports are free. Test-mode keys bill your real credit balance.\n- **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](https://diagrams.so/policy/trademark).\n- **Security:** report vulnerabilities to security@diagrams.so per [SECURITY.md](./SECURITY.md).\n",
  "bytes": 12772,
  "sha": "fb04003f0f03f81668cd582134e57e3be057f6de8226f892e6c21b06728d6158",
  "repo_slug": "redhold/diagrams-mcp-app-core",
  "fonte": "repo",
  "truncated": false,
  "api": "https://agentalog.com/api/listings/mcp_io_github_redhold_diagrams_so_mcp_a030930d/readme"
}