DBHub Universal Database Gateway MCP Server

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     +--->+    SQL Server    |
 |                  |    |              |    |                  |
 |  Other Clients   +--->+              +--->+    SQLite        |
 |                  |    |              |    |                  |
 |                  |    |              +--->+    MySQL         |
 |                  |    |              |    |                  |
 |                  |    |              +--->+    MariaDB       |
 |                  |    |              |    |                  |
 |                  |    |              +--->+    Oracle        |
 |                  |    |              |    |                  |
 +------------------+    +--------------+    +------------------+
      MCP Clients           MCP Server             Databases

Demo HTTP Endpoint

https://demo.dbhub.ai/message connects a sample employee database. You can point Cursor or MCP Inspector to it to see it in action.

mcp-inspector

Supported Matrix

Database Resources

Resource Name	URI Format	PostgreSQL	MySQL	MariaDB	SQL Server	SQLite	Oracle
schemas	`db://schemas`	✅	✅	✅	✅	✅	✅
tables_in_schema	`db://schemas/{schemaName}/tables`	✅	✅	✅	✅	✅	✅
table_structure_in_schema	`db://schemas/{schemaName}/tables/{tableName}`	✅	✅	✅	✅	✅	✅
indexes_in_table	`db://schemas/{schemaName}/tables/{tableName}/indexes`	✅	✅	✅	✅	✅	✅
procedures_in_schema	`db://schemas/{schemaName}/procedures`	✅	✅	✅	✅	❌	✅
procedure_details_in_schema	`db://schemas/{schemaName}/procedures/{procedureName}`	✅	✅	✅	✅	❌	✅

Database Tools

Tool	Command Name	Description	PostgreSQL	MySQL	MariaDB	SQL Server	SQLite	Oracle
Execute SQL	`execute_sql`	Execute single or multiple SQL statements (separated by semicolons)	✅	✅	✅	✅	✅	✅

Prompt Capabilities

Prompt	Command Name	PostgreSQL	MySQL	MariaDB	SQL Server	SQLite	Oracle
Generate SQL	`generate_sql`	✅	✅	✅	✅	✅	✅
Explain DB Elements	`explain_db`	✅	✅	✅	✅	✅	✅

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 sample employee database
docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport http \
   --port 8080 \
   --demo

# Oracle example
docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport http \
   --port 8080 \
   --dsn "oracle://username:password@localhost:1521/service_name"

# Oracle example with thick mode for connecting to 11g or older
docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub-oracle-thick \
   --transport http \
   --port 8080 \
   --dsn "oracle://username:password@localhost:1521/service_name"

NPM

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

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

Note: The demo mode includes a bundled SQLite sample "employee" database with tables for employees, departments, salaries, and more.

Claude Desktop

claude-desktop

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

// 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"]
    }
  }
}

Cursor

cursor

Cursor supports both stdio and http.
Follow Cursor MCP guide and make sure to use Agent mode.

Usage

SSL Connections

You can specify the SSL mode using the sslmode parameter in your DSN string:

Database	`sslmode=disable`	`sslmode=require`	Default SSL Behavior
PostgreSQL	✅	✅	Certificate verification
MySQL	✅	✅	Certificate verification
MariaDB	✅	✅	Certificate verification
SQL Server	✅	✅	Certificate verification
Oracle	✅	✅	N/A (use Oracle client config)
SQLite	❌	❌	N/A (file-based)

SSL Mode Options:

sslmode=disable: All SSL/TLS encryption is turned off. Data is transmitted in plaintext.
sslmode=require: Connection is encrypted, but the server's certificate is not verified. This provides protection against packet sniffing but not against man-in-the-middle attacks. You may use this for trusted self-signed CA.

Without specifying sslmode, most databases default to certificate verification, which provides the highest level of security.

Example usage:

# 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

Read-only Mode

You can run DBHub in read-only mode, which restricts SQL query execution to read-only operations:

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

In read-only mode, only readonly SQL operations are allowed.

This provides an additional layer of security when connecting to production databases.

Configure your database connection

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

npx @bytebase/dbhub  --demo

[!WARNING] If your user/password contains special characters, you need to escape them first. (e.g. pass#word should be escaped as pass%23word)

For real databases, a Database Source Name (DSN) is required. You can provide this in several ways:

Command line argument (highest priority):

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

Environment variable (second priority):

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

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
```

[!WARNING] When running in Docker, use host.docker.internal instead of localhost to connect to databases running on your host machine. For example: mysql://user:[email protected]:3306/dbname

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:`
Oracle	`oracle://[user]:[password]@[host]:[port]/[service_name]`	`oracle://username:password@localhost:1521/service_name?sslmode=disable`

Oracle

If you see the error "NJS-138: connections to this database server version are not supported by node-oracledb in Thin mode", you need to use Thick mode as described below.

Docker

Use bytebase/dbhub-oracle-thick instead of bytebase/dbhub docker image.

npx

Download and install Oracle Instant Client for your platform
Set the ORACLE_LIB_DIR environment variable to the path of your Oracle Instant Client:

# Set environment variable to Oracle Instant Client directory
export ORACLE_LIB_DIR=/path/to/instantclient_19_8

# Then run DBHub
npx @bytebase/dbhub --dsn "oracle://username:password@localhost:1521/service_name"

SQL Server

Extra query parameters:

authentication

authentication=azure-active-directory-access-token. Only applicable when running from Azure. See DefaultAzureCredential.

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"

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
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`
demo	N/A	Run in demo mode with sample employee database	`false`

The demo mode uses an in-memory SQLite database loaded with the sample employee database that includes tables for employees, departments, titles, salaries, department employees, and department managers. The sample database includes SQL scripts for table creation, data loading, and testing.

Development

Install dependencies:
```
pnpm install
```
Run in development mode:
```
pnpm dev
```

Build for production:

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

Testing

The project uses Vitest for comprehensive unit testing:

Run all tests: pnpm test
Run tests in watch mode: pnpm test:watch

Pre-commit Hooks (for Developers)

The project includes pre-commit hooks to run tests automatically before each commit:

After cloning the repository, set up the pre-commit hooks:
```
./scripts/setup-husky.sh
```
This ensures the test suite runs automatically whenever you create a commit, preventing commits that would break tests.

Debug with MCP Inspector

stdio

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

HTTP

# Start DBHub with HTTP transport
pnpm dev --transport=http --port=8080

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

Connect to the DBHub server /message endpoint

DBHub

Demo HTTP Endpoint

Supported Matrix

Database Resources

Database Tools

Prompt Capabilities

Installation

Docker

NPM

Claude Desktop

Cursor

Usage

SSL Connections

Read-only Mode

Configure your database connection

Oracle

Docker

npx

SQL Server

authentication

Transport

Command line options

Development

Testing

Pre-commit Hooks (for Developers)

Debug with MCP Inspector

stdio

HTTP

Contributors

Star History

Related MCP Server Picks for You

Be the First to Experience MCP Now