dbdiagram-mcp

module
v0.0.0-...-c6efd61 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 18, 2026 License: MIT

README

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.

Tools

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.

Directories

Path Synopsis
cmd
dbdiagram-mcp command
Command dbdiagram-mcp serves the dbdiagram.io public API as an MCP server.
Command dbdiagram-mcp serves the dbdiagram.io public API as an MCP server.
internal
dbdiagram
Package dbdiagram is a thin client for the dbdiagram.io public API v1.
Package dbdiagram is a thin client for the dbdiagram.io public API v1.
mcpserver
Package mcpserver exposes the dbdiagram.io public API as MCP tools.
Package mcpserver exposes the dbdiagram.io public API as MCP tools.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL