MCP Server

Active

MIT

DBHub MCP Server

io.github.bytebase/dbhub

Token-efficient MCP gateway for querying PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite.

What is the DBHub MCP server?

DBHub is a lightweight, zero-dependency MCP server that lets AI clients like Claude Desktop, Cursor, and VS Code connect to and query relational databases including PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite. It exposes just two token-efficient MCP tools for executing SQL and exploring schemas, and supports connecting to multiple databases simultaneously via TOML configuration.

DBHub is a minimal MCP server from Bytebase that acts as a gateway between MCP clients (Claude Desktop, Claude Code, Cursor, VS Code, Copilot CLI) and multiple database engines. It focuses on being lightweight and token-efficient, exposing only a small set of MCP tools to keep context windows small, while supporting guardrails like read-only mode, row limiting, and query timeouts, plus secure access via SSH tunneling and SSL/TLS. It also includes a built-in web workbench for running queries and custom tools outside of an MCP client, and supports connecting to multiple databases at once via TOML configuration.

How to install DBHub

Copy-paste configuration for popular MCP clients.

transport: stdio

Config generated by PluginBench — verify against the source before use.

Environment / auth

DSN
secret
Database connection string (e.g., postgres://user:pass@host:5432/db)
DB_TYPE
Database type: postgres, mysql, mariadb, sqlserver, sqlite
DB_HOST
Database hostname
DB_PORT
Database port
DB_USER
Database username
DB_PASSWORD
secret
Database password
DB_NAME
Database name or SQLite file path
TRANSPORT
Transport mode: stdio or http
PORT
HTTP server port (default: 8080)
ID
Instance identifier for tool names
SSH_HOST
SSH server hostname
SSH_PORT
SSH server port (default: 22)
SSH_USER
SSH username
SSH_PASSWORD
secret
SSH password
SSH_KEY
Path to SSH private key
SSH_PASSPHRASE
secret
SSH key passphrase

Claude Desktop

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

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub"
      ],
      "env": {
        "DSN": "<YOUR_DSN>",
        "DB_TYPE": "<YOUR_DB_TYPE>",
        "DB_HOST": "<YOUR_DB_HOST>",
        "DB_PORT": "<YOUR_DB_PORT>",
        "DB_USER": "<YOUR_DB_USER>",
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_NAME": "<YOUR_DB_NAME>",
        "TRANSPORT": "<YOUR_TRANSPORT>",
        "PORT": "<YOUR_PORT>",
        "ID": "<YOUR_ID>",
        "SSH_HOST": "<YOUR_SSH_HOST>",
        "SSH_PORT": "<YOUR_SSH_PORT>",
        "SSH_USER": "<YOUR_SSH_USER>",
        "SSH_PASSWORD": "<YOUR_SSH_PASSWORD>",
        "SSH_KEY": "<YOUR_SSH_KEY>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}

Cursor

~/.cursor/mcp.json

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub"
      ],
      "env": {
        "DSN": "<YOUR_DSN>",
        "DB_TYPE": "<YOUR_DB_TYPE>",
        "DB_HOST": "<YOUR_DB_HOST>",
        "DB_PORT": "<YOUR_DB_PORT>",
        "DB_USER": "<YOUR_DB_USER>",
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_NAME": "<YOUR_DB_NAME>",
        "TRANSPORT": "<YOUR_TRANSPORT>",
        "PORT": "<YOUR_PORT>",
        "ID": "<YOUR_ID>",
        "SSH_HOST": "<YOUR_SSH_HOST>",
        "SSH_PORT": "<YOUR_SSH_PORT>",
        "SSH_USER": "<YOUR_SSH_USER>",
        "SSH_PASSWORD": "<YOUR_SSH_PASSWORD>",
        "SSH_KEY": "<YOUR_SSH_KEY>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}

Windsurf

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub"
      ],
      "env": {
        "DSN": "<YOUR_DSN>",
        "DB_TYPE": "<YOUR_DB_TYPE>",
        "DB_HOST": "<YOUR_DB_HOST>",
        "DB_PORT": "<YOUR_DB_PORT>",
        "DB_USER": "<YOUR_DB_USER>",
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_NAME": "<YOUR_DB_NAME>",
        "TRANSPORT": "<YOUR_TRANSPORT>",
        "PORT": "<YOUR_PORT>",
        "ID": "<YOUR_ID>",
        "SSH_HOST": "<YOUR_SSH_HOST>",
        "SSH_PORT": "<YOUR_SSH_PORT>",
        "SSH_USER": "<YOUR_SSH_USER>",
        "SSH_PASSWORD": "<YOUR_SSH_PASSWORD>",
        "SSH_KEY": "<YOUR_SSH_KEY>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}

VS Code

.vscode/mcp.json

{
  "servers": {
    "dbhub": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@bytebase/dbhub"
      ],
      "env": {
        "DSN": "<YOUR_DSN>",
        "DB_TYPE": "<YOUR_DB_TYPE>",
        "DB_HOST": "<YOUR_DB_HOST>",
        "DB_PORT": "<YOUR_DB_PORT>",
        "DB_USER": "<YOUR_DB_USER>",
        "DB_PASSWORD": "<YOUR_DB_PASSWORD>",
        "DB_NAME": "<YOUR_DB_NAME>",
        "TRANSPORT": "<YOUR_TRANSPORT>",
        "PORT": "<YOUR_PORT>",
        "ID": "<YOUR_ID>",
        "SSH_HOST": "<YOUR_SSH_HOST>",
        "SSH_PORT": "<YOUR_SSH_PORT>",
        "SSH_USER": "<YOUR_SSH_USER>",
        "SSH_PASSWORD": "<YOUR_SSH_PASSWORD>",
        "SSH_KEY": "<YOUR_SSH_KEY>",
        "SSH_PASSPHRASE": "<YOUR_SSH_PASSPHRASE>"
      }
    }
  }
}

Claude Code

claude mcp add dbhub --env DSN=<YOUR_DSN> --env DB_TYPE=<YOUR_DB_TYPE> --env DB_HOST=<YOUR_DB_HOST> --env DB_PORT=<YOUR_DB_PORT> --env DB_USER=<YOUR_DB_USER> --env DB_PASSWORD=<YOUR_DB_PASSWORD> --env DB_NAME=<YOUR_DB_NAME> --env TRANSPORT=<YOUR_TRANSPORT> --env PORT=<YOUR_PORT> --env ID=<YOUR_ID> --env SSH_HOST=<YOUR_SSH_HOST> --env SSH_PORT=<YOUR_SSH_PORT> --env SSH_USER=<YOUR_SSH_USER> --env SSH_PASSWORD=<YOUR_SSH_PASSWORD> --env SSH_KEY=<YOUR_SSH_KEY> --env SSH_PASSPHRASE=<YOUR_SSH_PASSPHRASE> -- npx -y @bytebase/dbhub

Tools & capabilities

Tools this server exposes to the agent.

execute_sql — Execute SQL queries with transaction support and safety controls.
search_objects — Search and explore database schemas, tables, columns, indexes, and procedures with progressive disclosure.
Custom Tools — Define reusable, parameterized SQL operations in a dbhub.toml configuration file.

Use cases

Let an AI coding assistant query and explore a PostgreSQL, MySQL, MariaDB, SQL Server, or SQLite database directly
Connect to and switch between multiple databases (e.g., production, staging, development) from one MCP server using TOML config
Run read-only, row-limited, or timeout-protected queries to safely explore production data
Define custom parameterized SQL tools for repeated operations exposed to MCP clients
Use the built-in web workbench to test queries and custom tools without an MCP client

DBHub MCP server FAQ

What is the DBHub MCP server?

DBHub is a minimal MCP server that connects AI clients like Claude Desktop, Cursor, and VS Code to databases such as PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite through a single, token-efficient interface with just two core MCP tools.

Is DBHub free to use?

Yes, DBHub is open source and free, distributed via npm (@bytebase/dbhub) and as a Docker image (bytebase/dbhub).

What databases does DBHub support?

PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite.

How do I install DBHub?

Run it via Docker (`docker run bytebase/dbhub --transport http --port 8080 --dsn <connection-string>`) or via npm (`npx @bytebase/dbhub@latest --transport http --port 8080 --dsn <connection-string>`), then point your MCP client (Claude Desktop, Cursor, VS Code, etc.) at the server. A --demo mode is also available for trying it without a real database.

Does DBHub require authentication?

DBHub itself does not authenticate HTTP clients, so for production use it recommends binding to 127.0.0.1 and fronting it with a reverse proxy or firewall; database access is authenticated via the connection DSN, with optional SSH tunneling and SSL/TLS for secure database connections.

Can DBHub connect to multiple databases at once?

Yes, using a TOML configuration file you can define multiple database connections (e.g., production, staging, development) and access them all from a single DBHub instance.

README (reference)

Source of truth, from the repository.

[!NOTE]
Brought to you by Bytebase, open-source database DevSecOps platform.

            +------------------+    +--------------+    +------------------+
            |                  |    |              |    |                  |
            |                  |    |              |    |                  |
            |  Claude Desktop  +--->+              +--->+    PostgreSQL    |
            |                  |    |              |    |                  |
            |  Claude Code     +--->+              +--->+    SQL Server    |
            |                  |    |              |    |                  |
            |  Cursor          +--->+    DBHub     +--->+    SQLite        |
            |                  |    |              |    |                  |
            |  VS Code         +--->+              +--->+    MySQL         |
            |                  |    |              |    |                  |
            |  Copilot CLI     +--->+              +--->+    MariaDB       |
            |                  |    |              |    |                  |
            |                  |    |              |    |                  |
            +------------------+    +--------------+    +------------------+
                 MCP Clients           MCP Server             Databases

DBHub is a zero-dependency, token efficient MCP server implementing the Model Context Protocol (MCP) server interface. This lightweight gateway allows MCP-compatible clients to connect to and explore different databases:

Local Development First: Zero dependency, token efficient with just two MCP tools to maximize context window
Multi-Database: PostgreSQL, MySQL, MariaDB, SQL Server, and SQLite through a single interface
Multi-Connection: Connect to multiple databases simultaneously with TOML configuration
Guardrails: Read-only mode, row limiting, and query timeout to prevent runaway operations
Secure Access: SSH tunneling and SSL/TLS encryption

Supported Databases

PostgreSQL, MySQL, SQL Server, MariaDB, and SQLite.

MCP Tools

DBHub implements MCP tools for database operations:

execute_sql: Execute SQL queries with transaction support and safety controls
search_objects: Search and explore database schemas, tables, columns, indexes, and procedures with progressive disclosure
Custom Tools: Define reusable, parameterized SQL operations in your dbhub.toml configuration file

Workbench

DBHub includes a built-in web interface for interacting with your database tools. It provides a visual way to execute queries, run custom tools, and view request traces without requiring an MCP client.

workbench

Installation

See the full Installation Guide for detailed instructions.

Quick Start

Docker:

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

NPM: (requires Node.js >= 22.5.0)

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

Demo Mode:

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

Restrict to loopback (recommended for production):

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

The HTTP transport defaults to --host 0.0.0.0, exposing DBHub on every network interface. For production, bind to 127.0.0.1 and front DBHub with a reverse proxy (nginx/Caddy) or firewall — DBHub does not authenticate HTTP clients.

The HTTP transport also has built-in DNS-rebinding protection: it only accepts requests whose Host is loopback, this machine's own hostname/IPs, or a name you allow via --allowed-hosts. If a client behind a reverse proxy or custom DNS name gets a 403, add that hostname with --allowed-hosts.

See Command-Line Options for all available parameters.

Multi-Database Setup

Connect to multiple databases simultaneously using TOML configuration files. Perfect for managing production, staging, and development databases from a single DBHub instance.

See Multi-Database Configuration for complete setup instructions.

Development

Requires Node.js >= 22.5.0 (DBHub uses the built-in node:sqlite module).

# Install dependencies
pnpm install

# Run in development mode
pnpm dev

# Build and run for production
pnpm build && pnpm start --transport stdio --dsn "postgres://user:password@localhost:5432/dbname"

See Testing and Debug.

Contributors

Star History

View repository →