DBHub (Universal Database Gateway) MCP server for AI agents

DBHub is a universal database gateway implementing the Model Context Protocol (MCP) server interface, allowing AI tools like Claude Desktop and Cursor to connect to and explore different databases. It serves as a bridge between MCP-compatible clients and various database systems including PostgreSQL, MySQL, SQL Server, SQLite, MariaDB, and Oracle.

Installation Options

Using Docker

For PostgreSQL connection:

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

To run in demo mode with a sample employee database:

docker run --rm --init \
   --name dbhub \
   --publish 8080:8080 \
   bytebase/dbhub \
   --transport http \
   --port 8080 \
   --demo

For Oracle connection:

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

For Oracle 11g or older (thick mode):

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"

Using NPM

PostgreSQL example:

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

Demo mode:

npx @bytebase/dbhub --transport http --port 8080 --demo

Configuring for AI Tools

Claude Desktop Configuration

Claude Desktop supports the stdio transport. Create a configuration file:

// claude_desktop_config.json
{
  "mcpServers": {
    "dbhub-postgres-docker": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "bytebase/dbhub",
        "--transport",
        "stdio",
        "--dsn",
        "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 Configuration

Cursor supports both stdio and http transports. You can use the install link on the DBHub GitHub page or configure it manually following the Cursor MCP guide, ensuring you use Agent mode.

Usage Options

SSL Configuration

Specify 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

Read-only Mode

Restrict SQL query execution to read-only operations:

npx @bytebase/dbhub --readonly --dsn "postgres://user:password@localhost:5432/dbname"

Database Connection Configuration

You can provide the Database Source Name (DSN) 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): Create .env.local (development) or .env (production) with:
```
DSN=postgres://user:password@localhost:5432/dbname?sslmode=disable
```

Connection String Formats

DBHub supports these database connection string formats:

MySQL: mysql://user:password@localhost:3306/dbname?sslmode=disable
MariaDB: mariadb://user:password@localhost:3306/dbname?sslmode=disable
PostgreSQL: postgres://user:password@localhost:5432/dbname?sslmode=disable
SQL Server: sqlserver://user:password@localhost:1433/dbname?sslmode=disable
SQLite: sqlite:///path/to/database.db, sqlite:C:/Users/YourName/data/database.db (Windows), or sqlite:///:memory:
Oracle: oracle://username:password@localhost:1521/service_name?sslmode=disable

Special Oracle Configuration

For older Oracle databases, you might need to use Thick mode:

With Docker: Use bytebase/dbhub-oracle-thick image

With npx:

Download and install Oracle Instant Client

Set the environment variable:

export ORACLE_LIB_DIR=/path/to/instantclient_19_8
npx @bytebase/dbhub --dsn "oracle://username:password@localhost:1521/service_name"

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
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 includes an in-memory SQLite database with tables for employees, departments, titles, salaries, and more for testing purposes.

How to add this MCP server to 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 > MCP and click "Add new global MCP server".

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

{
    "mcpServers": {
        "cursor-rules-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "cursor-rules-mcp"
            ]
        }
    }
}

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 explictly ask the agent to use the tool by mentioning the tool name and describing what the function does.