dbdiagram-mcp
An MCP server for dbdiagram.io. It gives an LLM agent the dbdiagram public API v1 as nine tools, so the agent can list, read, create, update and delete diagrams written in DBML, and manage the embed links that render them in docs and blog posts.
Written in Go, ships as a single static binary, speaks MCP over stdio or streamable HTTP.
dbdiagram's public API is in beta and only available on a paid plan. Without one the API answers 403 no matter what the token is.
Requirements
- A dbdiagram workspace on a paid plan.
- A workspace API token: open the workspace window in dbdiagram, go to the API Tokens tab, create one. The token is scoped to that workspace and grants access to every diagram in it.
- Go 1.25+ if you build from source.
Install
go install github.com/jtprogru/dbdiagram-mcp/cmd/dbdiagram-mcp@latest
From source:
git clone https://github.com/jtprogru/dbdiagram-mcp.git
cd dbdiagram-mcp
make build # -> ./bin/dbdiagram-mcp
With Docker:
docker build -t dbdiagram-mcp .
docker run --rm -p 8080:8080 -e DBDIAGRAM_API_TOKEN=... dbdiagram-mcp
Connect a client
Claude Code
claude mcp add dbdiagram --env DBDIAGRAM_API_TOKEN=your-token -- dbdiagram-mcp
Any client that reads .mcp.json / claude_desktop_config.json
{
"mcpServers": {
"dbdiagram": {
"command": "dbdiagram-mcp",
"env": {
"DBDIAGRAM_API_TOKEN": "your-token"
}
}
}
}
The server writes nothing to stdout except MCP traffic, so it is safe to run under any stdio client. Logs go to stderr.
| Tool |
What it does |
dbdiagram_list_diagrams |
Lists the workspace's diagrams, most recently updated first. Filters by name with query, pages with limit/offset, and omits DBML unless include_content is set. |
dbdiagram_get_diagram |
Reads one diagram with its full DBML. include_layout adds table positions, table groups, sticky notes and relationship paths. |
dbdiagram_create_diagram |
Creates a diagram from DBML and returns its ID and editor URL. |
dbdiagram_update_diagram |
Replaces name, DBML or detail level. Omitted fields keep their current value, and layout is preserved unless layout_json is passed. |
dbdiagram_delete_diagram |
Deletes a diagram permanently, embed link included. |
dbdiagram_get_embed_link |
Reads a diagram's embed link and its render settings. |
dbdiagram_create_embed_link |
Creates the embed link so the diagram can be put in an iframe. |
dbdiagram_update_embed_link |
Toggles the link on or off, switches dark mode, relationship highlighting or detail level. |
dbdiagram_delete_embed_link |
Deletes the embed link, breaking every page that embeds it. |
Every tool carries readOnlyHint / destructiveHint annotations, so a client can gate the destructive ones behind confirmation.
Two design decisions worth knowing about:
Updates never silently truncate. The API requires both name and content on every PUT. If the agent sends only one of them, the server reads the current diagram first and fills in the other, instead of blanking it.
List results stay small. DBML runs to hundreds of lines per diagram, so dbdiagram_list_diagrams returns IDs, names and timestamps by default. The agent fetches content one diagram at a time.
HTTP mode
dbdiagram-mcp -http 127.0.0.1:8080
The MCP endpoint is POST /mcp, and GET /healthz answers {"status":"ok"} for container health checks. The transport is stateless: each request carries its own short-lived session, so the server scales horizontally and keeps no session state.
Requests carrying a browser Origin header are rejected unless the origin is loopback or listed in -allow-origin. That is what stops a random web page from driving a locally bound server through DNS rebinding. Requests with no Origin at all are accepted, since non-browser MCP clients do not send one.
The server has no authentication of its own. Anyone who can reach the port can use your dbdiagram token. Bind it to 127.0.0.1, or put an authenticating reverse proxy in front of it.
Configuration
| Environment |
Flag |
Default |
Meaning |
DBDIAGRAM_API_TOKEN |
— |
required |
Workspace API token. |
DBDIAGRAM_API_BASE_URL |
— |
https://api.dbdiagram.io/v1 |
API endpoint override. |
DBDIAGRAM_HTTP_ADDR |
-http |
empty (stdio) |
Listen address for streamable HTTP. |
DBDIAGRAM_ALLOWED_ORIGINS |
-allow-origin |
loopback only |
Extra browser origins, comma separated. * disables the check. |
DBDIAGRAM_TIMEOUT |
-timeout |
30s |
Timeout for a single API call. |
Flags win over environment variables. -allow-origin is repeatable.
Rate limits and errors
dbdiagram throttles per user and endpoint, at most 120 requests per minute. On 429 the server surfaces the Retry-After value in the tool error, so the agent can back off instead of hammering.
Every API failure comes back as a tool error with the HTTP status, the API's own message, and a hint about what to do next: a 401 points at DBDIAGRAM_API_TOKEN, a 404 points at dbdiagram_list_diagrams for valid IDs, a 403 mentions the paid-plan requirement.
Development
make check # fmt, tidy, lint, test with the race detector
make test # just the tests
make lint # golangci-lint
Tests run the real MCP protocol over an in-memory transport against a fake dbdiagram API, so tool schemas, annotations and error mapping are all covered without touching the network.
License
MIT, see LICENSE.