<p align="center"> <a href="https://dbhub.ai/" target="_blank"> <picture> <img src="https://raw.githubusercontent.com/bytebase/dbhub/main/assets/logo-full.svg" width="50%"> </picture> </a> </p>

DBHub is a universal database gateway implementing the Model Context Protocol (MCP) server interface. This gateway allows MCP-compatible clients to connect to and explore different databases.

 +------------------+    +--------------+    +------------------+
 |                  |    |              |    |                  |
 |                  |    |              |    |                  |
 |  Claude Desktop  +--->+              +--->+    PostgreSQL    |
 |                  |    |              |    |                  |
 |      Cursor      +--->+    DBHub     +--->+      MySQL       |
 |                  |    |              |    |                  |
 |     Other MCP    +--->+              +--->+     SQLite       |
 |      Clients     |    |              |    |                  |
 |                  |    |              +--->+     DuckDB       |
 |                  |    |              |    |                  |
 |                  |    |              +--->+  Other Databases |
 |                  |    |              |    |                  |
 +------------------+    +--------------+    +------------------+
      MCP Clients           MCP Server             Databases

Features

• Browse available tables in the database
• View schema information for tables
• Run read-only SQL queries against the database
• Safety checks to prevent dangerous queries

Installation

Docker

docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport sse \
   --port 8080 \
   --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

NPM

npx @bytebase/dbhub --transport sse --port 8080 --dsn "postgres://user:password@localhost:5432/dbname"

Usage

Configure your database connection

Database Source Name (DSN) is required to connect to your database. You can provide this in several ways:

• Command line argument (highest priority):

  pnpm dev --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
  

• Environment variable (second priority):

  export DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable"
  pnpm dev
  

• Environment file (third priority):

  • For development: Create .env.local with your DSN
  • For production: Create .env with your DSN

  DSN=postgres://user:password@localhost:5432/dbname?sslmode=disable
  

Transport

• stdio (default) - for direct integration with tools like Claude Desktop:

  npx @bytebase/dbhub --transport stdio --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
  

• sse - for browser and network clients:

  npx @bytebase/dbhub --transport sse --port 5678 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
  

Command line options

| Option | Description | Default | | :-------- | :-------------------------------------------------------------- | :---------------------------------- | | dsn | Database connection string | Required if not set via environment | | transport | Transport mode: stdio or sse | stdio | | port | HTTP server port (only applicable when using --transport=sse) | 8080 |

Claude Desktop

• Claude Desktop only supports stdio transport https://github.com/orgs/modelcontextprotocol/discussions/16

Docker

// claude_desktop_config.json
{
  "mcpServers": {
    "dbhub": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        // Use host.docker.internal as the host if connecting to the local db
        "postgres://user:password@host.docker.internal:5432/dbname?sslmode=disable"
      ]
    }
  }
}

NPX

// claude_desktop_config.json
{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        "postgres://user:password@localhost:5432/dbname?sslmode=disable"
      ]
    }
  }
}

Development

1. Install dependencies:

   pnpm install
   

2. Run in development mode:

   pnpm dev
   

3. Build for production:

   pnpm build
   pnpm start --transport stdio --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
   

Debug with MCP Inspector

stdio

TRANSPORT=stdio DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable" npx @modelcontextprotocol/inspector node /path/to/dbhub/dist/index.js

SSE

# Start DBHub with SSE transport
pnpm dev --transport=sse --port=8080

# Start the MCP Inspector in another terminal
npx @modelcontextprotocol/inspector

Connect to the DBHub server /sse endpoint