Installation

npm

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

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:[email protected]: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"
    environment:
      - DBHUB_LOG_LEVEL=info
    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

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

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

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

Docker

Client Integration

Claude Code

Claude Desktop

Cursor

VS Code

Codex

Dify

LibreChat

Getting Started

MCP Tools

Workbench

Configuration

​npm

​Docker

​Client Integration

​Claude Code

​Claude Desktop

​Cursor

​VS Code

​Codex

​Dify

​LibreChat

npm

Docker

Client Integration

Claude Code

Claude Desktop

Cursor

VS Code

Codex

Dify

LibreChat