Introduction

@dineug/erd-editor-mcp is an MCP server that lets a coding agent edit erd-editor diagrams. Claude Code, Codex, and any other client of the Model Context Protocol get one tool per operation on a document: add a table, rename a column, relate two tables, import a DDL dump, read the schema back as SQL.

When the document is open in the ERD Editor of VS Code, Obsidian, or a JetBrains IDE, the agent joins the editor like a collaborator. Each change shows up on the canvas as it happens, and the agent's undo reverts only its own edits. VS Code keeps the agent's changes unsaved until the agent or you save, while Obsidian and a JetBrains IDE save them as they save your own. With no editor on the document, the same tools edit the file itself.

What an Agent Can Do

• Build or change a schema in conversation: tables, columns and every column option, relationships with their cardinality and their ON DELETE and ON UPDATE actions, indexes, memos, colors, and positions on the canvas. See Relationships.
• Gather tables in table groups: add a group around the tables it names or over an area of the canvas, then rename it, color it, move it with its tables, resize it, put tables in or take them out, or remove it, which leaves its tables where they are. See Table Groups.
• Name tables and columns from the words and terms of the editor's Dictionary tab, and link columns to its domains, which give them their data types. It sets the logical names of tables and columns, and the dictionaries derive the physical names from them as they do in the editor, though a physical name written by hand stays unless it is empty. It adds, changes, and removes domains, words, and terms, and after a word or term changes, derives the physical names again for one column, one table, or the whole document. It lists what the tab's Checks sheet finds: forbidden, unregistered, and synonym words; names that two rows of one dictionary share; links to a domain the document does not list; physical names other than the one their term gives; and columns off their domain's data type. See Dictionaries and Dictionary Checks.
• Replace the document with a schema parsed from SQL DDL, GraphQL SDL, DBML, or AML, or with another .erd.json document. Or add that schema or document below the diagram and keep everything already there, as the editor's Import and Add does. A DBML TableGroup arrives as a table group either way. A schema that replaces the document keeps the document's dictionaries, a document that replaces it brings its own, and an addition brings none. See Import.
• Read the diagram back, with its logical names and dictionary rows, as a list of ids, as whole entities, or as the .erd.json text a save writes. Or read it as DDL for any of the eight databases, with the Statements and Header choices of the Schema SQL tab and its Write logical names into empty comments switch. On a schema of thousands of tables it reads a page, a few tables, or the tables of a few table groups at a time. See Reading a Document.
• Set the database, the database name, and the scripts written before and after the tables in the Schema SQL, such as CREATE EXTENSION ahead of them or GRANT after them. erd_read gives the scripts alone, or within the DDL of the whole document. See Settings.
• Run several edits as one, all or none, which one undo reverts. See erd_batch.
• Undo and redo its own edits, never yours.

What it does not do:

• Zoom, scroll, or switch tabs. Those belong to each viewer, so no tool does so. An import that replaces the document still moves the view, even with Viewport locked, as the editor's Import does: back to the start of the canvas at 100%, or, with erd_import_json, to the view of the document it loads, and to its tab too unless that document locks Canvas Type. See Import.
• Switch the Name View between Physical Names, Logical Names, and Both Names. It belongs to each viewer while its lock is on, as it is in a new diagram, and is yours to pick in the editor once the lock is off, so no tool does so. The agent reads and writes logical names whatever the view. An erd_import_json that replaces the document brings the Name View of the document it loads only when that document has the Name View lock off.
• Change View Option, the Code Generator's language and name cases, the bracket type, or the Settings tab's Relationship DataType Sync, Maximum comment width, and Column Order. Those are yours to set in the editor, and the agent reads them as the file saves them.
• Turn a lock on or off. Only erd_import_json replacing the whole document changes the locks or the settings above, to those of the document it loads. A document with no lockSettings field, such as a file saved by the VS Code extension before 4.0.0 or by the Obsidian or JetBrains plugin before 1.0.0, turns every lock on. Undoing any import that replaced the document brings back the settings and locks the document had before.
• Re-map a relationship onto other columns, as Map Columns does. Instead, the agent removes the relationship, which leaves its foreign key columns in place, and links the columns it wants with erd_link_columns, in one erd_batch that one undo reverts.
• Import or export a dictionary as CSV, sort a sheet, or insert rows above or below a row, as the Dictionary tab does. The agent adds, changes, and removes rows, many at once in one erd_batch, and a new row goes at the end of its sheet.
• Run the Code Generator. erd_read answers DDL or JSON, and the agent writes code from that itself.

How It Works

The server is a stdio process your MCP client starts. For every call it looks for an editor that holds the document: a VS Code window, an Obsidian vault window, or a JetBrains IDE, each with the ERD Editor extension or plugin.

• Live — an editor has the document in its workspace, its vault, or one of its open projects, or has it open. The server joins that editor's editing session and the edit lands in the editor: unsaved in VS Code, and saved as your own edits are in Obsidian and a JetBrains IDE.
• Headless — no editor. The server loads the file, applies the edit, and writes the file back.
• Refused — an editor holds the document but has its hub off. The server reads from disk but writes nothing, since the open editor could overwrite the file on its next save. A JetBrains IDE with its hub on also refuses to change a document held only by projects it does not trust, though the agent can still read it. When the editor's hub is on but its ERD Editor extension or plugin speaks another hub protocol than the server, every call on the document is refused, reads included, with protocolMismatch and a message that names the side to update — see Updating.

See Live and Headless for the details.

Requirements

Node.js	22.12 or later, to run the server
An MCP client	Claude Code, Codex, or any client that can start a stdio server
VS Code, for live editing	1.101.0 or later, with the ERD Editor extension 4.0.0 or later
Obsidian, for live editing	The desktop app 1.5.7 or later, with the ERD Editor plugin 1.0.0 or later
A JetBrains IDE, for live editing	An IntelliJ-based IDE 2025.2 or later, with the ERD Editor plugin 1.0.0 or later

Server 1.0.0 or later and the releases above speak hub protocol 2. The earlier releases that serve agents speak protocol 1: the VS Code extension 3.0.0 to 3.1.0, the Obsidian plugin 0.1.0 and 0.2.0, and the JetBrains plugin 0.9.0 and 0.10.0. Such a release and server 1.0.0 or later refuse each other, and so do an earlier server and the releases above — see Updating. A VS Code extension before 3.0.0 or a JetBrains plugin before 0.9.0 has no hub, so the server does not see it and edits the file on disk, even a diagram open in it.

The tools for logical names, domains, and the dictionaries need server 1.1.0 or later and, wherever the document is open, at least the VS Code extension 4.2.0 or the Obsidian or JetBrains plugin 1.2.0. Of the releases above, an extension before 4.2.0 or a plugin before 1.2.0 still lets the agent edit live, since it speaks protocol 2, but it ignores the logical names, domain links, and dictionary rows the agent writes, and leaves them out when it saves the file. A server before 1.1.0 that edits a file on disk writes it back without its logical names, domain links, and dictionary rows — see Updating.

Next: Install.