Diagrams.so

@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. Sem 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) e então apenas peça um diagrama. Como a máquina ainda não está conectada, a primeira chamada de ferramenta responde com um link. Abra-o, 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 é só 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 então export_diagram. Você nunca nomeia uma ferramenta ou 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; leitura, avisos e cada exportação 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 do 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 reorganização de layout
search_gallery	Pesquisar diagramas públicos da comunidade + biblioteca selecionada
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 detalhado 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	❌	— (apenas 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 completa 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 do 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 desabilitar a conexão na ferramenta; ferramentas não autenticadas então apenas dizem para executar login)

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 pedindo um diagrama e clicando no link que a primeira chamada de ferramenta fornece. 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, mesma etapa login. É o pacote MCPB que o Smithery instala, não o pacote npm, então a versão mostrada lá segue 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 que 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 GitHub Release. 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 GitHub Release; workflow_dispatch manual o produz como um 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 apenas em stderr.
• Erros retornam 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 o 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, então clientes MCP que redefinem seu timeout de solicitação no progresso (resetTimeoutOnProgress) não abortarão uma geração lenta no padrão de 60s do SDK. Se seu cliente não redefine no 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