DBHub
by bytebase
<p align="center">
<a href="https://dbhub.ai/" target="_blank">
<picture>
<img src="https://raw.githubusercontent.com/bytebase/dbhub/main/assets/logo-full.svg" width="50%">
</picture>
</a>
</p>
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.
```bash
+------------------+ +--------------+ +------------------+
| | | | | |
| | | | | |
| Claude Desktop +--->+ +--->+ PostgreSQL |
| | | | | |
| Cursor +--->+ DBHub +--->+ MySQL |
| | | | | |
| Other MCP +--->+ +--->+ SQLite |
| Clients | | | | |
| | | +--->+ DuckDB |
| | | | | |
| | | +--->+ Other Databases |
| | | | | |
+------------------+ +--------------+ +------------------+
MCP Clients MCP Server Databases
```
## Features
- Browse available tables in the database
- View schema information for tables
- Run read-only SQL queries against the database
- Safety checks to prevent dangerous queries
## Installation
### Docker
```bash
docker run --rm --init \
--name dbhub \
--publish 8080:8080 \
bytebase/dbhub \
--transport sse \
--port 8080 \
--dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
```
### NPM
```bash
npx @bytebase/dbhub --transport sse --port 8080 --dsn "postgres://user:password@localhost:5432/dbname"
```
## Usage
### Configure your database connection
Database Source Name (DSN) is required to connect to your database. You can provide this in several ways:
- **Command line argument** (highest priority):
```bash
pnpm dev --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
```
- **Environment variable** (second priority):
```bash
export DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable"
pnpm dev
```
- **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
```
### Transport
- **stdio** (default) - for direct integration with tools like Claude Desktop:
```bash
npx @bytebase/dbhub --transport stdio --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
```
- **sse** - for browser and network clients:
```bash
npx @bytebase/dbhub --transport sse --port 5678 --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
```
### Command line options
| Option | Description | Default |
| :-------- | :-------------------------------------------------------------- | :---------------------------------- |
| dsn | Database connection string | Required if not set via environment |
| transport | Transport mode: `stdio` or `sse` | `stdio` |
| port | HTTP server port (only applicable when using `--transport=sse`) | `8080` |
### Claude Desktop

- Claude Desktop only supports `stdio` transport https://github.com/orgs/modelcontextprotocol/discussions/16
#### Docker
```json
// claude_desktop_config.json
{
"mcpServers": {
"dbhub": {
"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:password@host.docker.internal:5432/dbname?sslmode=disable"
]
}
}
}
```
#### NPX
```json
// claude_desktop_config.json
{
"mcpServers": {
"dbhub": {
"command": "npx",
"args": [
"-y",
"@bytebase/dbhub",
"--transport",
"stdio",
"--dsn",
"postgres://user:password@localhost:5432/dbname?sslmode=disable"
]
}
}
}
```
## Development
1. Install dependencies:
```bash
pnpm install
```
1. Run in development mode:
```bash
pnpm dev
```
1. Build for production:
```bash
pnpm build
pnpm start --transport stdio --dsn "postgres://user:password@localhost:5432/dbname?sslmode=disable"
```
### Debug with [MCP Inspector](https://github.com/modelcontextprotocol/inspector)
#### stdio
```bash
TRANSPORT=stdio DSN="postgres://user:password@localhost:5432/dbname?sslmode=disable" npx @modelcontextprotocol/inspector node /path/to/dbhub/dist/index.js
```
#### SSE
```bash
# Start DBHub with SSE transport
pnpm dev --transport=sse --port=8080
# Start the MCP Inspector in another terminal
npx @modelcontextprotocol/inspector
```
Connect to the DBHub server `/sse` endpoint
