Introdução

@dineug/erd-editor-mcp é um servidor MCP que permite a um agente de programação editar diagramas do erd-editor. O Claude Code, o Codex e qualquer outro cliente do Model Context Protocol recebem uma ferramenta por cada operação sobre um documento: adicionar uma tabela, mudar o nome de uma coluna, relacionar duas tabelas, importar um dump de DDL, ler o esquema de volta em SQL.

Quando o documento está aberto no ERD Editor do VS Code, do Obsidian ou de um IDE da JetBrains, o agente junta-se ao editor como um colaborador. Cada alteração aparece na tela à medida que acontece, e a anulação do agente reverte apenas as edições do próprio agente. O VS Code mantém as alterações do agente por guardar até serem guardadas pelo agente ou por si, enquanto o Obsidian e um IDE da JetBrains as guardam tal como guardam as edições feitas por si. Sem nenhum editor que detenha o documento, as mesmas ferramentas editam o próprio ficheiro.

O que um agente pode fazer

• Criar ou alterar um esquema numa conversa: tabelas, colunas e todas as opções das colunas, relações com a sua cardinalidade e as suas ações ON DELETE e ON UPDATE, índices, notas, cores e posições na tela. Consulte Relações.
• Reunir tabelas em grupos de tabelas: adicionar um grupo à volta das tabelas que indica ou sobre uma área da tela e, depois, mudar-lhe o nome, atribuir-lhe uma cor, movê-lo com as suas tabelas, redimensioná-lo, colocar tabelas nele ou retirá-las, ou removê-lo, o que deixa as suas tabelas onde estão. Consulte Grupos de tabelas.
• Substituir o documento por um esquema analisado a partir de SQL DDL, GraphQL SDL, DBML ou AML, ou por outro documento .erd.json. Ou adicionar esse esquema ou documento abaixo do diagrama e manter tudo o que já lá está, como faz a opção Import and Add do editor. Um TableGroup do DBML chega como grupo de tabelas em ambos os casos. Consulte Importação.
• Ler o diagrama de volta como uma lista de ids, como entidades completas, como o texto .erd.json que se escreve ao guardar ou como DDL para qualquer uma das oito bases de dados, com as opções Statements e Header do separador Esquema SQL. Num esquema de milhares de tabelas, lê uma página, algumas tabelas ou as tabelas de alguns grupos de tabelas de cada vez. Consulte Ler um documento.
• Definir a base de dados, o nome da base de dados e os scripts escritos antes e depois das tabelas no Esquema SQL, como um CREATE EXTENSION antes delas ou um GRANT depois delas. erd_read devolve os scripts isoladamente, ou dentro do DDL do documento inteiro. Consulte Definições.
• Executar várias edições como uma só, todas ou nenhuma, que uma única anulação reverte. Consulte erd_batch.
• Anular e refazer as edições do próprio agente, nunca as suas.

O que não faz:

• Fazer zoom, deslocar a vista ou mudar de separador. Essas ações pertencem a cada pessoa que vê o diagrama, pelo que nenhuma ferramenta o faz. Ainda assim, uma importação que substitui o documento move a vista, mesmo com a definição Viewport bloqueada, tal como faz a opção Import do editor: de volta ao início da tela a 100% ou, com erd_import_json, para a vista do documento que carrega, e também para o separador desse documento, a menos que este tenha a definição Canvas Type bloqueada. Consulte Importação.
• Alterar as opções do menu View Option, a linguagem e os formatos dos nomes do Gerador de código, o tipo de delimitador ou as definições Relationship DataType Sync, Maximum comment width e Column Order do separador Definições. Cabe-lhe a si defini-las no editor, e o agente lê-as tal como o ficheiro as guarda.
• Ativar ou desativar um bloqueio. Só erd_import_json, ao substituir o documento inteiro, altera os bloqueios ou as definições acima, para os do documento que carrega. Um documento sem o campo lockSettings, como um ficheiro guardado pela extensão do VS Code anterior à 4.0.0 ou pelo plugin do Obsidian ou da JetBrains anterior à 1.0.0, ativa todos os bloqueios. Anular qualquer importação que tenha substituído o documento repõe as definições e os bloqueios que o documento tinha antes.
• Voltar a mapear uma relação para outras colunas, como faz a opção Map Columns. Em vez disso, o agente remove a relação, o que deixa as suas colunas de chave externa no lugar, e liga as colunas que pretende com erd_link_columns, num só erd_batch que uma única anulação reverte.
• Executar o Gerador de código. erd_read responde com DDL ou JSON, e é o próprio agente que escreve o código a partir daí.

Como funciona

O servidor é um processo stdio que o seu cliente MCP inicia. Em cada chamada, procura um editor que detenha o documento: uma janela do VS Code, uma janela de cofre do Obsidian ou um IDE da JetBrains, cada um com a extensão ou o plugin ERD Editor.

• Em direto — um editor tem o documento na área de trabalho, no cofre ou num dos projetos abertos, ou tem-no aberto. O servidor junta-se à sessão de edição desse editor e a edição chega ao editor: por guardar no VS Code, e guardada, tal como as suas edições, no Obsidian e num IDE da JetBrains.
• Headless — nenhum editor. O servidor carrega o ficheiro, aplica a edição e volta a escrever o ficheiro.
• Recusado — um editor detém o documento, mas tem o hub desativado. O servidor lê a partir do disco, mas não escreve nada, uma vez que o editor aberto poderia substituir o ficheiro da próxima vez que guardar. Um IDE da JetBrains com o hub ativado também se recusa a alterar um documento detido apenas por projetos em que não confia, embora o agente continue a poder lê-lo. Quando o hub do editor está ativado, mas a extensão ou o plugin ERD Editor desse editor utiliza um protocolo do hub que não é o do servidor, todas as chamadas sobre o documento são recusadas, incluindo as leituras, com protocolMismatch e uma mensagem que indica o lado a atualizar — consulte Atualizar.

Consulte Em direto e headless para conhecer os pormenores.

Requisitos

Node.js	22.12 ou posterior, para executar o servidor
Um cliente MCP	Claude Code, Codex ou qualquer cliente que consiga iniciar um servidor stdio
VS Code, para a edição em direto	1.101.0 ou posterior, com a extensão ERD Editor 4.0.0 ou posterior
Obsidian, para a edição em direto	A aplicação para computador 1.5.7 ou posterior, com o plugin ERD Editor 1.0.0 ou posterior
Um IDE da JetBrains, para a edição em direto	Um IDE baseado no IntelliJ 2025.2 ou posterior, com o plugin ERD Editor 1.0.0 ou posterior

O servidor 1.0.0 e as versões acima utilizam o protocolo 2 do hub. As versões anteriores que servem agentes utilizam o protocolo 1: a extensão do VS Code da 3.0.0 à 3.1.0, o plugin do Obsidian 0.1.0 e 0.2.0 e o plugin da JetBrains 0.9.0 e 0.10.0. Uma dessas versões e o servidor 1.0.0 recusam-se mutuamente, e o mesmo acontece com um servidor anterior e as versões acima — consulte Atualizar. Uma extensão do VS Code anterior à 3.0.0 ou um plugin da JetBrains anterior à 0.9.0 não tem hub, pelo que o servidor não vê esse editor e edita o ficheiro no disco, mesmo que o diagrama esteja aberto nele.

Seguinte: Instalação.