@drawdb/mcp

A Model Context Protocol server that gives AI agents read-only access to your drawDB diagrams — so they can inspect your database schema (tables, columns, relationships, enums, custom types) while helping you write queries, migrations, or application code.

It runs locally over the stdio transport, which works with Claude Desktop, Cursor, Cline, Goose, Windsurf, and any other client that launches a local MCP child process.

Requirements

• Node.js ≥ 20
• A drawDB API key (starts with ddb_). Mint one from the drawDB Profile modal → API keys tab. Plain JWTs are not accepted on /api/v1.

You don't need to install anything ahead of time — the config below launches the server on demand with npx.

Quickstart

Add the server to your MCP client's config. For Claude Desktop (claude_desktop_config.json):

{
  "mcpServers": {
    "drawdb": {
      "command": "npx",
      "args": ["-y", "@drawdb/mcp"],
      "env": {
        "DRAWDB_API_KEY": "ddb_xxx"
      }
    }
  }
}

Cursor (~/.cursor/mcp.json, or .cursor/mcp.json in a project) uses the same shape. Restart the client after editing, then ask the agent something like "list my drawDB diagrams" to confirm the connection.

Once connected, a typical flow is: the agent calls list_diagrams to find a diagram's ID, then passes that diagram_id to any of the schema tools below.

Tools

All tools are read-only — the server has no way to mutate a diagram.

Tool	Args	Returns
list_diagrams	—	id / name / database / updatedAt for every diagram the key can see
get_schema_summary	diagram_id	dialect + counts + table list
list_tables	diagram_id	name + comment + field count for each table
describe_table	diagram_id, table_name	full column definitions, indices, comments
list_relationships	diagram_id	every FK with cardinality + ON UPDATE/DELETE
describe_relationship	diagram_id, from_table, to_table	filtered relationship info
list_enums	diagram_id	user-defined enums
list_custom_types	diagram_id	Postgres composite types
search_tables	diagram_id, query	substring matches across table/column names + comments

Table and relationship lookups are case-insensitive.

Configuration

The server is configured entirely through environment variables (set in the env block of your client config, or exported in your shell for local runs):

Variable	Required	Default	Description
DRAWDB_API_KEY	yes	—	Your drawDB API key (ddb_…).
DRAWDB_BASE_URL	no	https://api.drawdb.app	Override to point at a self-hosted or local backend (e.g. http://localhost:4000).

Auth model

• API keys are minted from the drawDB Profile modal → API keys tab.
• A key inherits the user's plan and access, and lists diagrams across every team the user belongs to — there is no per-workspace scoping, so the agent sees them all.
• Read-only by design; the server exposes no mutating tools.
• Revoking a key immediately invalidates every agent that holds it.

Development

npm install
npm run dev        # run from source with tsx (reads .env if present)
npm run typecheck  # tsc --noEmit
npm run build      # compile to dist/
npm start          # run the compiled dist/stdio.js

Copy .env.example to .env and drop in your key to run against the live backend, or point DRAWDB_BASE_URL at a local drawDB server.

To test a local build inside an MCP client, swap the command/args in your config for an absolute node invocation:

{
  "command": "node",
  "args": ["/absolute/path/to/drawdb-mcp/dist/stdio.js"],
  "env": { "DRAWDB_API_KEY": "ddb_xxx" }
}

Architecture

The server is a thin layer over the drawDB backend's read API:

• src/stdio.ts — entry point (the drawdb-mcp bin); reads env, wires up stdio.
• src/server.ts — builds the McpServer and registers tools.
• src/tools.ts — the nine tool handlers and their response shaping.
• src/api.ts — DrawDBClient, an HTTP wrapper over GET /api/v1/diagrams and GET /api/v1/diagrams/:id/schema, authenticated with the X-API-Key header.
• src/types.ts — the diagram schema shape returned by the backend.

License

MIT — see LICENSE.