Installation

npm

The npm method requires Node.js >= 22.5.0 (DBHub uses Node’s built-in node:sqlite module). The Docker image bundles a compatible Node runtime, so no local Node install is needed when running via Docker.

npx
Global Installation

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

# Or use demo mode for testing
npx @bytebase/dbhub@latest --transport http --port 8080 --demo

# Install globally
npm install -g @bytebase/dbhub@latest

# Run the server
dbhub --transport http --port 8080 --dsn "postgres://..."

# Or use demo mode for testing
dbhub --transport http --port 8080 --demo

Minimal Installation

By default, DBHub attempts to install drivers for all supported databases (PostgreSQL, MySQL, MariaDB, SQL Server, SQLite). If you only need specific databases, you can skip the unnecessary drivers to reduce installation size. This applies to npm install (global or local). When using npx, npm will attempt to install all optional dependencies, but some drivers may be skipped if their installation fails, a required transitive dependency is missing, or the platform is not supported.

# Install with only the PostgreSQL driver
npm install -g @bytebase/dbhub@latest --omit=optional && npm install -g pg

# Install with only PostgreSQL and MySQL drivers
npm install -g @bytebase/dbhub@latest --omit=optional && npm install -g pg mysql2

Available driver packages:

pg — PostgreSQL
mysql2 — MySQL
mariadb — MariaDB
mssql — SQL Server

SQLite uses the built-in node:sqlite module (Node.js 22.5+), so it requires no driver package or native compilation and is always available.

When a driver is not installed or a required dependency is missing (e.g., a transitive dependency like @azure/core-client for the SQL Server driver), DBHub will skip that connector at startup and log a message. All other connectors will work normally. SQLite (including --demo mode) needs no extra driver — it relies on the built-in node:sqlite module.

MCP Bundle (.mcpb)

The MCP Bundle is a one-click install for MCPB-compatible clients — Claude Desktop, Claude Code, MCP for Windows: download the .mcpb from the latest release, install, enter your connection string. Read-only by default, no Node.js or JSON editing required — the recommended path for non-technical users. The guide also covers packaging your own bundle.

Claude Code Plugin

The Claude Code Plugin registers the DBHub MCP server in Claude Code with one install command and adds /dbhub:setup and /dbhub:explore skills. Claude Code prompts for the connection string and keeps it in secure storage. Read-only by design, like the MCP Bundle.

Docker

Docker Run
Docker Compose

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

# Or use demo mode for testing
docker run --rm --init \
  --name dbhub \
  --publish 8080:8080 \
  bytebase/dbhub \
  --transport http \
  --port 8080 \
  --demo

When connecting to databases on your host machine from Docker, use host.docker.internal instead of localhost:

--dsn "postgres://user:password@host.docker.internal:5432/dbname"

For development environments using Docker Compose, add DBHub to your docker-compose.yml:

docker-compose.yml

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

  database:
    image: postgres:15-alpine
    environment:
      POSTGRES_PASSWORD: password
      POSTGRES_DB: dbname

Client Integration

Once DBHub is installed and running, configure your MCP client to connect to it.

Claude Code

Prefer a one-command, read-only install with a prompted connection string? Use the Claude Code Plugin. The manual registration below gives full control over flags, transports, and TOML configs.

CLI
Project Configuration
User Configuration

Stdio
HTTP

For local database connections, use stdio transport:

claude mcp add --transport stdio dbhub -- npx @bytebase/dbhub@latest --transport stdio --dsn "postgres://user:password@localhost:5432/dbname"

The -- separates Claude’s flags from DBHub’s arguments. Everything after -- is the DBHub command.

For remote or shared database servers, use HTTP transport:

claude mcp add --transport http dbhub http://localhost:8080/mcp

This connects to a DBHub server running with HTTP transport:

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

For project-specific database connections shared with your team, create .mcp.json in your project root.

Stdio
HTTP

.mcp.json

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

Use environment variable expansion for sensitive values:

.mcp.json

{
  "mcpServers": {
    "dbhub": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--transport",
        "stdio",
        "--dsn",
        "${DATABASE_URL}"
      ]
    }
  }
}

.mcp.json

{
  "mcpServers": {
    "dbhub": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

For personal configuration across all projects:

claude mcp add --scope user dbhub -- npx @bytebase/dbhub@latest --transport stdio --dsn "postgres://user:password@localhost:5432/dbname"

Or manually edit the user configuration file:

MacOS/Linux
Windows

Edit ~/.claude/settings.json and add to the mcpServers section.

Edit %USERPROFILE%\.claude\settings.json and add to the mcpServers section.

Using DBHub: Start Claude Code in your project directory:

claude

Verify DBHub is loaded:

/mcp

References:

Claude Code MCP Documentation

Claude Desktop

Prefer a one-click, read-only install with no JSON editing? Use the MCP Bundle. The manual config below gives full control over flags and transports.

MacOS/Linux
Windows
Demo Mode

Edit ~/Library/Application Support/Claude/claude_desktop_config.json:

~/Library/Application Support/Claude/claude_desktop_config.json

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

Edit %APPDATA%\Claude\claude_desktop_config.json:

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

For testing, you can use the built-in demo database:

~/Library/Application Support/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--transport",
        "stdio",
        "--demo"
      ]
    }
  }
}

Troubleshooting:

Verify your DSN connection string is correct
Check that the database is accessible from your machine
Review Claude Desktop logs: ~/Library/Logs/Claude/mcp*.log (MacOS)

References:

Claude Desktop MCP Documentation

Cursor

One-Click Install
Stdio (Local)
HTTP (Remote)
Project-Specific

Click the link below to install DBHub in Cursor:

After installing, edit the DSN in your Cursor MCP settings to point to your database.

For local database connections, use stdio transport:MacOS/Linux - Edit ~/.cursor/mcp.json:

~/.cursor/mcp.json

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

Windows - Edit %USERPROFILE%\.cursor\mcp.json:

%USERPROFILE%.cursor\mcp.json

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

For remote or shared database servers, use HTTP transport:MacOS/Linux - Edit ~/.cursor/mcp.json:

~/.cursor/mcp.json

{
  "mcpServers": {
    "dbhub": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

Windows - Edit %USERPROFILE%\.cursor\mcp.json:

%USERPROFILE%.cursor\mcp.json

{
  "mcpServers": {
    "dbhub": {
      "url": "http://localhost:8080/mcp"
    }
  }
}

This connects to a DBHub server running with HTTP transport:

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

For project-specific database connections, create .cursor/mcp.json in your project root:

.cursor/mcp.json

{
  "mcpServers": {
    "project-db": {
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--transport",
        "stdio",
        "--config",
        "${workspaceFolder}/dbhub.toml"
      ]
    }
  }
}

References:

Cursor MCP Documentation

VS Code

VS Code has native MCP support through GitHub Copilot. Create .vscode/mcp.json in your project root:

Stdio (Local)
HTTP (Remote)
Input Variables
Config File

For local database connections, use stdio transport:

.vscode/mcp.json

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

For remote or shared database servers, use HTTP transport:

.vscode/mcp.json

{
  "servers": {
    "dbhub": {
      "type": "http",
      "url": "http://localhost:8080/mcp"
    }
  }
}

This connects to a DBHub server running with HTTP transport:

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

For sensitive data like passwords, use input variables:

.vscode/mcp.json

{
  "inputs": [
    {
      "type": "promptString",
      "id": "db-dsn",
      "description": "Database connection string",
      "password": true
    }
  ],
  "servers": {
    "dbhub": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--transport",
        "stdio",
        "--dsn",
        "${input:db-dsn}"
      ]
    }
  }
}

For multi-database setups, use a config file:

.vscode/mcp.json

{
  "servers": {
    "dbhub": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--transport",
        "stdio",
        "--config",
        "${workspaceFolder}/dbhub.toml"
      ]
    }
  }
}

References:

VS Code MCP Documentation

GitHub Copilot CLI

Interactive
Config File
Demo Mode

Use the Copilot CLI to interactively add the MCP server:

/mcp add

When prompted, you’ll need to provide:

Server type: select local (the default)
Server name: for example, dbhub
Command: npx @bytebase/dbhub@latest
Arguments: transport (e.g., --transport stdio) and connection details (either --dsn connection string or --demo for the demo database)

Create or edit the configuration file ~/.copilot/mcp-config.json:

~/.copilot/mcp-config.json

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

For testing, use the built-in demo database:

~/.copilot/mcp-config.json

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "@bytebase/dbhub@latest",
        "--transport",
        "stdio",
        "--demo"
      ]
    }
  }
}

References:

Copilot CLI MCP Documentation

Codex

CLI
TOML
Verification

# Connect to your database
codex mcp add dbhub -- npx @bytebase/dbhub@latest --transport stdio --dsn "postgres://user:password@localhost:5432/dbname"

# Or use demo mode for testing
codex mcp add dbhub -- npx @bytebase/dbhub@latest --transport stdio --demo

~/.codex/config.toml

# Connect to your database
[mcp_servers.dbhub]
command = "npx"
args = ["@bytebase/dbhub@latest", "--transport", "stdio", "--dsn", "postgres://user:password@localhost:5432/dbname"]

# Or use demo mode for testing
[mcp_servers.dbhub]
command = "npx"
args = ["@bytebase/dbhub@latest", "--transport", "stdio", "--demo"]

/mcp

🔌  MCP Tools

  • dbhub
    • Status: enabled
    • Auth: Unsupported
    • Command: npx -y @bytebase/dbhub@latest --demo
    • Tools: execute_sql
    • Resources: schemas (db://schemas)
    • Resource templates: 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_detail_in_schema (db://schemas/{schemaName}/procedures/{procedureName})

References:

Codex MCP Documentation

Dify

DBHub must be running as an HTTP server for Dify to connect. Start DBHub with HTTP transport:

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

Configuration:

In Dify, navigate to Tools → MCP
Click Add MCP Server (HTTP)
Configure the server:
- Server URL: http://localhost:8080/mcp (or your DBHub host)
- Name: DBHub
- Server Identifier: dbhub (permanent, max 24 characters)
Click save. Dify will automatically discover DBHub’s tools.

Using DBHub Tools: Once connected, DBHub tools are available in:

Agents: Tools appear alongside built-in tools, use “Add All” to enable all DBHub tools
Workflows: Tools appear as available node types

Multi-Database Setup: For multiple databases, use a config file:

npx @bytebase/dbhub@latest --transport http --port 8080 --config /path/to/dbhub.toml

Demo Mode: For testing, use the built-in demo database:

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

Limitations:

Dify only supports HTTP transport (not stdio)
DBHub must be network-accessible from Dify

References:

Dify MCP Documentation

LibreChat

DBHub can be integrated with LibreChat using either stdio or Streamable HTTP transport.

stdio
Streamable HTTP

librechat.yaml

mcpServers:
  dbhub:
    type: stdio
    command: npx
    args:
      - -y
      - "@bytebase/dbhub@latest"
      - "--dsn"
      - "postgres://user:password@localhost:5432/dbname"
    timeout: 60000

For demo mode:

librechat.yaml

mcpServers:
  dbhub:
    type: stdio
    command: npx
    args:
      - -y
      - "@bytebase/dbhub@latest"
      - "--demo"
    timeout: 60000

librechat.yaml

mcpServers:
  dbhub:
    type: streamable-http
    url: http://host.docker.internal:8080/mcp
    timeout: 60000

Docker Networking: When LibreChat runs in Docker (e.g., with docker-compose), use host.docker.internal:8080 to connect to DBHub running on your host machine. This is Docker’s special DNS name that resolves to the host’s IP address.For native installations, use http://localhost:8080/mcp instead.

References:

LibreChat MCP Documentation

Getting Started

MCP Tools

Workbench

Configuration

npm

Minimal Installation

MCP Bundle (.mcpb)

Claude Code Plugin

Docker

Client Integration

Claude Code

Claude Desktop

Cursor

VS Code

GitHub Copilot CLI

Codex

Dify

LibreChat

​npm

​Minimal Installation

​MCP Bundle (.mcpb)

​Claude Code Plugin

​Docker

​Client Integration

​Claude Code

​Claude Desktop

​Cursor

​VS Code

​GitHub Copilot CLI

​Codex

​Dify

​LibreChat

npm

Minimal Installation

MCP Bundle (.mcpb)

Claude Code Plugin

Docker

Client Integration

Claude Code

Claude Desktop

Cursor

VS Code

GitHub Copilot CLI

Codex

Dify

LibreChat