DBHub (Universal Database Gateway) MCP server for AI agents

DBHub is a universal database gateway implementing the Model Context Protocol (MCP) server interface. It enables MCP-compatible clients like Claude, Cursor, or VSCode with Copilot to connect to and interact with various databases including PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite.

Installation

Docker

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

# Demo mode with sqlite sample employee database
docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport http \
   --port 8080 \
   --demo

Docker Compose Setup

dbhub:
  image: bytebase/dbhub:latest
  container_name: dbhub
  ports:
    - "8080:8080"
  environment:
    - DBHUB_LOG_LEVEL=info
  command:
    - --transport
    - http
    - --port
    - "8080"
    - --dsn
    - "postgres://user:password@database:5432/dbname"
  depends_on:
    - database

NPM

# PostgreSQL example
npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

# Demo mode with sqlite sample employee database
npx @bytebase/dbhub --transport http --port 8080 --demo

Claude Desktop Configuration

Claude Desktop only supports stdio transport:

// claude_desktop_config.json
{
  "mcpServers": {
    "dbhub-postgres-docker": {
      "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:[email protected]:5432/dbname?sslmode=disable"
      ]
    },
    "dbhub-postgres-npx": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        "postgres://user:password@localhost:5432/dbname?sslmode=disable"
      ]
    },
    "dbhub-demo": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub", "--transport", "stdio", "--demo"]
    }
  }
}

VSCode + Copilot

VSCode with GitHub Copilot can connect to DBHub via both stdio and http transports:

Stdio Transport:

{
  "servers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        "postgres://user:password@localhost:5432/dbname"
      ]
    }
  },
  "inputs": []
}

HTTP Transport:

{
  "servers": {
    "dbhub": {
      "url": "http://localhost:8080/message",
      "type": "http"
    }
  },
  "inputs": []
}

Usage

Read-only Mode

You can run DBHub in read-only mode to restrict SQL query execution to read-only operations:

# Enable read-only mode
npx @bytebase/dbhub --readonly --dsn "postgres://user:password@localhost:5432/dbname"

Row Limiting

Limit the number of rows returned from SELECT queries:

# Limit SELECT queries to return at most 1000 rows
npx @bytebase/dbhub --dsn "postgres://user:password@localhost:5432/dbname" --max-rows 1000

SSL Connections

Specify the SSL mode using the sslmode parameter in your DSN string:

# Disable SSL
postgres://user:password@localhost:5432/dbname?sslmode=disable

# Require SSL without certificate verification
postgres://user:password@localhost:5432/dbname?sslmode=require

# Standard SSL with certificate verification (default)
postgres://user:password@localhost:5432/dbname

SSH Tunnel Support

DBHub supports connecting to databases through SSH tunnels:

Using SSH Config File (Recommended)

# If you have this in ~/.ssh/config:
# Host mybastion
#   HostName bastion.example.com
#   User ubuntu
#   IdentityFile ~/.ssh/id_rsa

npx @bytebase/dbhub \
  --dsn "postgres://dbuser:[email protected]:5432/mydb" \
  --ssh-host mybastion

SSH with Password Authentication

npx @bytebase/dbhub \
  --dsn "postgres://dbuser:[email protected]:5432/mydb" \
  --ssh-host bastion.example.com \
  --ssh-user ubuntu \
  --ssh-password mypassword

SSH with Private Key Authentication

npx @bytebase/dbhub \
  --dsn "postgres://dbuser:[email protected]:5432/mydb" \
  --ssh-host bastion.example.com \
  --ssh-user ubuntu \
  --ssh-key ~/.ssh/id_rsa

Configure Your Database Connection

You can use DBHub in demo mode with a sample employee database for testing:

npx @bytebase/dbhub --demo

For real databases, you can configure the connection in two ways:

Method 1: Database Source Name (DSN)

# Command line argument
npx @bytebase/dbhub --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"

# Environment variable
export DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable"
npx @bytebase/dbhub

Method 2: Individual Database Parameters

# Environment variables
export DB_TYPE=postgres
export DB_HOST=localhost
export DB_PORT=5432
export DB_USER=myuser
export DB_PASSWORD='my@complex:password/with#special&chars'
export DB_NAME=mydatabase
npx @bytebase/dbhub

DBHub supports the following database connection string formats:

Database	DSN Format	Example
MySQL	`mysql://[user]:[password]@[host]:[port]/[database]`	`mysql://user:password@localhost:3306/dbname?sslmode=disable`
MariaDB	`mariadb://[user]:[password]@[host]:[port]/[database]`	`mariadb://user:password@localhost:3306/dbname?sslmode=disable`
PostgreSQL	`postgres://[user]:[password]@[host]:[port]/[database]`	`postgres://user:password@localhost:5432/dbname?sslmode=disable`
SQL Server	`sqlserver://[user]:[password]@[host]:[port]/[database]`	`sqlserver://user:password@localhost:1433/dbname?sslmode=disable`
SQLite	`sqlite:///[path/to/file]` or `sqlite:///:memory:`	`sqlite:///path/to/database.db`, `sqlite:C:/Users/YourName/data/database.db (windows)` or `sqlite:///:memory:`

Transport Options

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

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

http - for browser and network clients:

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

Command Line Options

Option	Environment Variable	Description	Default
dsn	`DSN`	Database connection string	Required if not in demo mode
N/A	`DB_TYPE`	Database type: `postgres`, `mysql`, `mariadb`, `sqlserver`, `sqlite`	N/A
N/A	`DB_HOST`	Database server hostname (not needed for SQLite)	N/A
N/A	`DB_PORT`	Database server port (uses default if omitted, not needed for SQLite)	N/A
N/A	`DB_USER`	Database username (not needed for SQLite)	N/A
N/A	`DB_PASSWORD`	Database password (not needed for SQLite)	N/A
N/A	`DB_NAME`	Database name or SQLite file path	N/A
transport	`TRANSPORT`	Transport mode: `stdio` or `http`	`stdio`
port	`PORT`	HTTP server port (only applicable when using `--transport=http`)	`8080`
readonly	`READONLY`	Restrict SQL execution to read-only operations	`false`
max-rows	N/A	Limit the number of rows returned from SELECT queries	No limit
demo	N/A	Run in demo mode with sample employee database	`false`
ssh-host	`SSH_HOST`	SSH server hostname for tunnel connection	N/A
ssh-port	`SSH_PORT`	SSH server port	`22`
ssh-user	`SSH_USER`	SSH username	N/A
ssh-password	`SSH_PASSWORD`	SSH password (for password authentication)	N/A
ssh-key	`SSH_KEY`	Path to SSH private key file	N/A
ssh-passphrase	`SSH_PASSPHRASE`	Passphrase for SSH private key	N/A

How to install this MCP server

For Claude Code

To add this MCP server to Claude Code, run this command in your terminal:

claude mcp add-json "dbhub" '{"command":"npx","args":["-y","@bytebase/dbhub"],"env":{"TRANSPORT":"stdio","DSN":"postgres://user:password@localhost:5432/dbname?sslmode=disable","READONLY":"true"}}'

See the official Claude Code MCP documentation for more details.

For Cursor

There are two ways to add an MCP server to Cursor. The most common way is to add the server globally in the ~/.cursor/mcp.json file so that it is available in all of your projects.

If you only need the server in a single project, you can add it to the project instead by creating or adding it to the .cursor/mcp.json file.

Adding an MCP server to Cursor globally

To add a global MCP server go to Cursor Settings > Tools & Integrations and click "New MCP Server".

When you click that button the ~/.cursor/mcp.json file will be opened and you can add your server like this:

{
    "mcpServers": {
        "dbhub": {
            "command": "npx",
            "args": [
                "-y",
                "@bytebase/dbhub"
            ],
            "env": {
                "TRANSPORT": "stdio",
                "DSN": "postgres://user:password@localhost:5432/dbname?sslmode=disable",
                "READONLY": "true"
            }
        }
    }
}

Adding an MCP server to a project

To add an MCP server to a project you can create a new .cursor/mcp.json file or add it to the existing one. This will look exactly the same as the global MCP server example above.

How to use the MCP server

Once the server is installed, you might need to head back to Settings > MCP and click the refresh button.

The Cursor agent will then be able to see the available tools the added MCP server has available and will call them when it needs to.

You can also explicitly ask the agent to use the tool by mentioning the tool name and describing what the function does.

For Claude Desktop

To add this MCP server to Claude Desktop:

1. Find your configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json

2. Add this to your configuration file:

{
    "mcpServers": {
        "dbhub": {
            "command": "npx",
            "args": [
                "-y",
                "@bytebase/dbhub"
            ],
            "env": {
                "TRANSPORT": "stdio",
                "DSN": "postgres://user:password@localhost:5432/dbname?sslmode=disable",
                "READONLY": "true"
            }
        }
    }
}

3. Restart Claude Desktop for the changes to take effect