db-diagram-tool-mcp

A Model Context Protocol server (stdio) that lets MCP clients — Claude Code and OpenAI Codex — read your DB Diagram Tool diagrams (list them; fetch a schema as JSON, DBML, or SQL DDL) and, with a write-scoped token, create and update them from DBML.

It talks to the DB Diagram Tool backend over its normal REST API, authenticated with a Personal Access Token (PAT). A read PAT can only read; the write tools require a write PAT. Writes merge into the live document like a collaborator typing (concurrent editors are never clobbered), and deletions are never applied without your explicit confirmation (see below).

Tools

Read (a read or write PAT):

| Tool | Args | Returns | |------|------|---------| | list_diagrams | — | The diagrams your token can access (id, name, role, visibility, updated time). | | get_diagram | id | Metadata + the full schema snapshot (tables, columns, relationships) as JSON. | | get_diagram_dbml | id | The diagram rendered as DBML (dbdiagram.io text format). | | get_diagram_sql | id, dialect? (postgres | mysql, default postgres) | Server-generated CREATE TABLE SQL DDL. |

Write (a write PAT):

| Tool | Args | Returns | |------|------|---------| | create_diagram | name, dbml | Creates a new diagram from DBML (you own it); returns the new id + an editor URL. | | update_diagram | id, dbml, confirmDeletions? | Merges the DBML into the live diagram. Additions/changes apply at once; table/column deletions are withheld and returned as pendingDeletions until you re-call with confirmDeletions: true. |

Delete safety (two-call handshake). If your DBML drops a table or column, update_diagram applies nothing destructive and lists what would be deleted. The agent shows you those, and only after you approve does it call again with confirmDeletions: true. A paste that forgets a table can't silently destroy it.

Requirements

• Node.js ≥ 18 (uses the built-in fetch).
• A Personal Access Token for your DB Diagram Tool account (create one in the app's Settings → Personal Access Tokens). It looks like ddt_pat_…. Choose the write scope if you want the create/update tools; read is enough (and safer) for read-only use.
• The backend origin URL (e.g. http://localhost:8090 for local dev, or your hosted instance).

Configuration

The server reads these environment variables (set them in your MCP client's server config, below):

| Variable | Required | Example | Notes | |----------|----------|---------|-------| | DDT_BASE_URL | yes | http://localhost:8090 | Backend origin only — scheme + host[:port], no /api/v1 path. | | DDT_PAT | yes | ddt_pat_abc123… | Your personal access token. Treat it like a password. | | DDT_WS_URL | no | wss://relay.example.com | Relay WS origin for write-back. Defaults to DDT_BASE_URL with http→ws / https→wss — only set it when the realtime relay is on a different host than the REST API. | | DDT_APP_URL | no | https://app.example.com | Web app origin, used for the editor URL create_diagram returns. Defaults to DDT_BASE_URL. |

Build

Not published to npm yet — build it locally and point your client at the compiled entry (dist/index.js):

cd db-diagram-tool-mcp
npm install
npm run build
# entry point: <this dir>/dist/index.js  (use its ABSOLUTE path below)

Install in Claude Code

CLI (adds it for you):

claude mcp add --transport stdio db-diagram-tool \
  --env DDT_BASE_URL=http://localhost:8090 \
  --env DDT_PAT=ddt_pat_your_token_here \
  -- node /ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js

--scope defaults to local (this project, private to you); add --scope user to enable it everywhere, or --scope project to write a shared, git-tracked .mcp.json.

Or a project .mcp.json (git-tracked; shared with your team):

{
  "mcpServers": {
    "db-diagram-tool": {
      "command": "node",
      "args": ["/ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js"],
      "env": {
        "DDT_BASE_URL": "http://localhost:8090",
        "DDT_PAT": "${DDT_PAT}"
      }
    }
  }
}

Don't commit your token. Claude Code expands ${VAR} (and ${VAR:-default}) in .mcp.json, so use "DDT_PAT": "${DDT_PAT}" and export DDT_PAT in your shell — the raw token stays out of the repo.

Install in Codex

CLI:

codex mcp add db-diagram-tool \
  --env DDT_BASE_URL=http://localhost:8090 \
  --env DDT_PAT=ddt_pat_your_token_here \
  -- node /ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js

(The -- before the command is required.)

Or ~/.codex/config.toml (global) — or .codex/config.toml in a project:

[mcp_servers.db-diagram-tool]
command = "node"
args = ["/ABSOLUTE/PATH/TO/db-diagram-tool-mcp/dist/index.js"]

[mcp_servers.db-diagram-tool.env]
DDT_BASE_URL = "http://localhost:8090"
DDT_PAT = "ddt_pat_your_token_here"

Codex TOML does not expand ${VAR} — use literal values, and keep the file private (don't commit a token).

Try it

Once configured, ask your agent things like:

• "List my DB Diagram Tool diagrams."
• "Show the DBML for the diagram named Blog."
• "Give me the Postgres DDL for diagram <id>."
• "Create a diagram called Orders from this DBML: …" (write PAT)
• "Add a status column to orders in diagram <id>." (write PAT)

Security

• Scoped tokens. A read PAT reaches only the four diagram-read endpoints; a write PAT additionally creates/updates diagrams. Neither can read member emails or comments, or manage tokens. Prefer read unless you want write-back.
• The PAT never touches the relay. For a live write, the server exchanges the write PAT for a short-lived (~120s), single-diagram aud:"ws" token and uses that for the realtime handshake — a leaked handshake token can't act as a REST session or reach another diagram.
• Deletions need your confirmation. update_diagram never drops a table or column on the first call — it reports pendingDeletions and applies them only when you re-call with confirmDeletions: true.
• Store your PAT like a password — prefer ${DDT_PAT} env expansion (Claude Code) over inlining, and never commit it.

Notes

• diagramToDbml.ts is ported verbatim from the web app (db-diagram-tool-fe/src/lib/dbml/diagramToDbml.ts); keep the two in sync.
• src/core/ vendors the web app's DBML↔diagram + Yjs bridge modules verbatim (only import paths rewritten). A drift-guard test (src/core/vendored.drift.test.ts) fails if they diverge from the FE source — re-vendor and re-run the golden when the FE changes.
• Built against @modelcontextprotocol/sdk v1.30; write-back builds to REST contract v1.7.0 (/pats/ws-token, write-scoped PATs).