Diagrams.so

Gere e edite diagramas de arquitetura de nuvem como arquivos draw.io nativos, a partir de um prompt ou do Terraform

Documentação

@diagrams-so/mcp

O servidor MCP Diagrams.so — gere, edite e gerencie diagramas de arquitetura de nuvem a partir de qualquer cliente MCP (Claude Desktop, Claude Code, Cursor). É um cliente stdio leve sobre a API pública do Diagrams.so (/api/v2); cada ferramenta é uma chamada REST.

Início rápido

Requer Node ≥ 18. Nenhuma chave de API para copiar: você se conecta aprovando em um navegador.

# 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

Reinicie seu cliente e então pergunte: "Gere um diagrama de aplicação web de 3 camadas na AWS e mostre-me os avisos." Execute /mcp se quiser confirmar primeiro que todas as 23 ferramentas estão registradas.

Usando muito? Instale uma vez e o comando fica mais curto:

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

O servidor fala com a produção (https://api.diagrams.so/api/v2) por padrão. Aponte-o para uma API local ou auto-hospedada com DIAGRAMS_API_BASE.

Usando Claude Desktop ou Cursor em vez do CLI? Veja Adicione ao seu cliente MCP. Prefere uma instalação com um clique, sem terminal? Veja Instalação com um clique (MCPB).

Sem terminal algum (Claude Desktop)

Adicione o servidor à configuração do seu cliente (abaixo) com DIAGRAMS_LOGIN_EMAIL definido para seu e-mail, e então basta pedir um diagrama. Como a máquina ainda não está conectada, a primeira chamada de ferramenta envia um código de acesso único por e-mail e responde com um link. Abra-o, insira o código, pressione Aprovar e pergunte novamente. Nada para instalar ou digitar.

Gerando um diagrama a partir do Claude

login apenas conecta a máquina. Ele nunca gera nada por conta própria, então não há comando generate para digitar em um terminal. Você escreve o prompt na caixa de chat normal do seu assistente e ele chama as ferramentas para você.

Cliente	Onde você digita o prompt
Claude Code	o chat do terminal, no mesmo lugar onde você pergunta qualquer outra coisa
Claude Desktop	a caixa de mensagem normal
Cursor	o painel de chat ou compositor

Os servidores MCP carregam na inicialização, então reinicie seu cliente após adicioná-lo. Em seguida, execute /mcp e confirme que diagrams-so mostra 23 ferramentas.

Agora basta perguntar, em português simples:

Gere uma aplicação web de três camadas na AWS com um ALB, EC2 Auto Scaling e RDS Multi-AZ. Mostre-me os avisos de design e exporte como draw.io.

Por trás dessa frase, o assistente chama generate_diagram, depois get_warnings e export_diagram. Você nunca nomeia uma ferramenta nem escreve JSON.

Mais coisas que valem a pena pedir, uma vez que você tem um diagrama:

Os avisos mencionam ausência de criptografia em trânsito. Corrija isso e mostre-me a nova pontuação.

Adicione uma distribuição CloudFront na frente do ALB.

Re-exporte como SVG para eu colocar no README.

Cada resposta traz o custo em créditos e seu saldo restante. Gerar, editar, corrigir e reorganizar o layout gastam créditos; leituras, avisos e todas as exportações são gratuitos.

O arquivo .drawio que o assistente salva abre em app.diagrams.net ou no aplicativo desktop, totalmente editável — é XML real do draw.io, não uma imagem.

Prefere não usar um assistente? diagrams.so/create tem a mesma coisa como página web: digite o prompt na caixa. Sem instalação, sem login, sem MCP.

Ferramentas (23)

Criar e alterar (mutação)

Ferramenta	O que faz	Custo
`generate_diagram`	Criar um diagrama a partir de um prompt → id + XML draw.io + avisos + pontuação	créditos
`edit_diagram`	Aplicar uma alteração em linguagem natural (nova versão)	créditos
`fix_warning`	Resolver um aviso do Well-Architected	créditos
`relayout_diagram`	Reorganizar o layout com IA (assíncrono; primeiros 2/diagrama gratuitos, depois confirmação)	créditos*
`import_diagram`	Importar XML draw.io existente como novo diagrama	gratuito
`update_diagram`	Renomear / alterar visibilidade / substituir XML	gratuito
`revert_diagram`	Reverter para uma versão anterior	gratuito
`delete_diagram`	Exclusão suave de um diagrama (destrutivo)	gratuito
`fork_template`	Copiar um diagrama público/biblioteca para sua conta (privado)	gratuito

Leitura (gratuita)

Ferramenta	O que faz
`get_diagram`	Buscar o XML + pontuação de um diagrama
`list_diagrams`	Listar seus diagramas (paginação por cursor)
`get_warnings`	Descobertas Well-Architected para um diagrama
`export_diagram`	Arquivo `drawio` ou `svg` bruto (gratuito em todos os planos; SVG do plano gratuito tem marca d'água)
`list_versions`	Histórico de versões (com `is_current`)
`get_version`	XML + pontuação de uma versão específica
`get_relayout_status`	Consultar um trabalho assíncrono de re-layout
`search_gallery`	Pesquisar diagramas públicos da comunidade + biblioteca curada
`enhance_prompt`	Transformar uma ideia vaga em um prompt detalhado
`clarify_prompt`	Obter perguntas de esclarecimento para um prompt vago
`get_usage`	Plano + créditos + estimativas de custo
`get_usage_history`	Registro de créditos itemizado por tarefa (ação, créditos, diagrama, superfície) com filtros + total da sessão ao vivo
`whoami`	Conta, plano, escopos, modo ao vivo/teste
`list_capabilities`	Tipos de diagrama / provedores / formatos de exportação válidos

Leituras e exportações são gratuitas; generate / edit / fix / relayout custam créditos, e delete é destrutivo. relayout pede confirm=true antes de cobrar.

CLI

Comandos

Instalar o pacote coloca diagrams-so no seu PATH. O nome mais longo diagrams-so-mcp ainda funciona, e npx @diagrams-so/mcp <command> funciona sem instalar nada.

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

Ambiente

Variável	Obrigatória	Padrão
`DIAGRAMS_API_KEY`	❌	— (somente CI e headless; `login` é o caminho normal)
`DIAGRAMS_API_BASE`	❌	`https://api.diagrams.so/api/v2` (produção; substitua para local/auto-hospedado)
`DIAGRAMS_API_TIMEOUT_MS`	❌	`450000` (rede de segurança por solicitação; fica acima da escada de timeouts do lado do servidor da API)
`DIAGRAMS_BROWSER`	❌	— (`login` abre seu navegador padrão; defina, por exemplo, `Google Chrome` quando sua sessão Diagrams.so estiver em um navegador não padrão)
`DIAGRAMS_NO_BROWSER`	❌	— (defina qualquer valor para impedir que `login` abra um navegador; a URL é sempre impressa)
`DIAGRAMS_NO_AUTO_LOGIN`	❌	— (defina qualquer valor para desativar a conexão na ferramenta; ferramentas não autenticadas então apenas dizem para executar `login`)
`DIAGRAMS_LOGIN_EMAIL`	❌	— (endereço para conexão na ferramenta: o código de acesso único é enviado por e-mail para lá; sem ele, ferramentas não autenticadas dizem para executar `login` em vez de iniciar uma conexão)

Adicione ao seu cliente MCP

O pacote publicado roda direto do npm, então não há caminho para preencher nem chave na configuração. Execute npx @diagrams-so/mcp install para imprimir esses blocos para seu cliente.

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
    }
  }
}

Conecte executando npx @diagrams-so/mcp login uma vez ou, com DIAGRAMS_LOGIN_EMAIL definido, pedindo um diagrama e seguindo o link que a primeira chamada de ferramenta fornece (o código de acesso chega por e-mail). Defina DIAGRAMS_API_KEY apenas para CI e máquinas headless, onde nenhum navegador pode abrir.

Reinicie o cliente e então pergunte: "Gere um diagrama de aplicação web de 3 camadas na AWS e mostre-me os avisos."

Instalação com um clique (MCPB)

Baixe diagrams-so.mcpb do último lançamento e arraste-o para o Claude Desktop. Sem terminal, e não pede mais chave de API: instale e conecte no primeiro uso clicando no link que a primeira chamada de ferramenta fornece.

Compilar o pacote você mesmo é uma etapa de contribuidor; veja Desenvolvendo localmente.

Smithery

O servidor está listado em smithery.ai/servers/diagrams-so/mcp, que o instala para você e lista todas as 23 ferramentas com seus parâmetros:

npx -y smithery mcp add diagrams-so/mcp

Mesmo pacote, mesmo passo login. É o pacote MCPB que o Smithery instala, não o pacote npm, então a versão mostrada lá segue os lançamentos em vez de npm dist-tags.

Verifique se funciona

DIAGRAMS_API_KEY=dgz_live_your_key node test-smoke.mjs

Executa o fluxo completo (conectar → listar ferramentas → whoami → gerar → avisos → corrigir → exportar → tratamento de erros).

Integração contínua e lançamentos

Workflow	Gatilho	O que faz
CI (`ci.yml`)	todo push / PR	`npm ci` + `npm run build` no Node 18/20/22, depois um smoke gratuito (`scripts/ci-smoke.mjs`) que inicia o servidor compilado e verifica se todas as 23 ferramentas registram. Sem chamadas de API, sem créditos.
Smoke ao vivo (`live-smoke.yml`)	noturno + manual	o fluxo completo de ponta a ponta (`test-smoke.mjs`) contra a API real. Gasta créditos — roda apenas quando o segredo `DIAGRAMS_API_KEY` está definido.
Lançamento (`release.yml`)	tag `vX.Y.Z`	build → `npm prune --omit=dev` → empacotar `diagrams-so.mcpb` → anexar a um lançamento do GitHub. Publica no npm também se um segredo `NPM_TOKEN` estiver definido.

Corte um lançamento:

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

A tag deve corresponder ao version de package.json (o workflow impõe isso). O pacote .mcpb aparece no lançamento do GitHub; workflow_dispatch manual o produz como artefato baixável sem publicar (útil para testar um pacote).

Segredos/variáveis do repositório (opcional): DIAGRAMS_API_KEY (smoke ao vivo), NPM_TOKEN (publicação npm), variável DIAGRAMS_API_BASE (destino de smoke ao vivo não produção).

Notas

stdout é o canal MCP — o servidor registra logs apenas no stderr.
Erros voltam como erros limpos de ferramenta MCP carregando o code da API, status HTTP e request_id.
O servidor nunca fala com serviços internos ou banco de dados — apenas o /api/v2 público.
Ferramentas de longa duração permanecem ativas além dos timeouts do cliente. generate / edit / fix / relayout / enhance_prompt / clarify_prompt emitem um notifications/progress a cada 10s enquanto executam, para que clientes MCP que redefinem o timeout de solicitação em progresso (resetTimeoutOnProgress) não abortem uma geração lenta no padrão de 60s do SDK. Se seu cliente não redefine em progresso, aumente o timeout por chamada para essas ferramentas.

Desenvolvendo localmente

Necessário apenas se você estiver alterando o próprio servidor. Usuários devem instalar do npm; veja Início rápido.

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

Licença e aspectos legais

Código: Apache-2.0. Veja NOTICE.
Serviço: este servidor é um cliente da API Diagrams.so. O uso da API é regido pelos Termos de Serviço e pela Política de Uso Aceitável; a licença do código não concede direitos sobre a própria API.
Privacidade: o servidor roda localmente, conecta-se apenas a api.diagrams.so e não contém telemetria. Credenciais de login são armazenadas em ~/.diagrams-so/credentials.json com permissões somente do proprietário. Veja a Política de Privacidade.
Cobrança: operações de gerar, editar, corrigir, re-layout e fork custam créditos; leituras e exportações são gratuitas. Chaves em modo de teste cobram seu saldo real de créditos.
Marcas registradas: Diagrams.so e o logotipo Diagrams.so são marcas registradas da RedHold LLC. Esta licença não concede permissão para usá-las, exceto para descrever com precisão a origem do pacote. Veja a Política de Marcas Registradas.
Segurança: relate vulnerabilidades para security@diagrams.so conforme SECURITY.md.