DBHub Documentation

DBHub is a zero-dependency, token-efficient MCP (Model Context Protocol) server that acts as a lightweight gateway between MCP-compatible clients (like Claude Desktop, Claude Code, Cursor, or VS Code) and various databases. It allows AI assistants to explore and interact with database schemas and data through a standardized interface.

Supported Databases:

• PostgreSQL
• MySQL
• SQL Server
• MariaDB
• SQLite

DBHub provides three types of tools for interacting with databases via AI models:

1. Execute SQL (execute_sql or execute_sql_{id}): Executes single or multiple SQL statements (separated by semicolons).
2. Search Objects (search_objects or search_objects_{id}): Searches and lists database objects like schemas, tables, columns, procedures, and indexes using pattern matching.
3. Custom Tools: User-defined, parameterized SQL operations defined in your dbhub.toml configuration file.

Postgres MCP servers can be categorized based on whether they are vendor-neutral or vendor-specific, and whether they are PostgreSQL-specific or data source agnostic.

• Postgres-specific & Vendor-neutral: Anthropic's original reference implementation, Postgres MCP Pro by Crystal DBA.
• Postgres-specific & Vendor-specific: Supabase MCP Server, Neon MCP Server.
• Multi-database & Vendor-neutral: DBHub.
• Multi-database & Vendor-specific: MCP Toolbox for Databases by Google.

Run DBHub as a Docker container to expose an HTTP transport for your database. Use the --dsn flag to provide your database connection string.

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

Database sources define the connections DBHub uses to interact with databases. Each source is defined in a [[sources]] block within your dbhub.toml file. You can identify sources using a unique id and provide a description to help AI models understand the data's purpose.

Sources can be configured using a single Data Source Name (dsn) or by specifying individual connection parameters (useful for handling special characters in passwords without URL encoding).

[[sources]]
id = "production"
description = "Production PostgreSQL database containing customer and order data"
dsn = "postgres://user:pass@prod.example.com:5432/myapp?sslmode=require"

Development requires Node.js >= 22.5.0. Use pnpm for managing the project.

# 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"

To install DBHub as a native plugin in Claude Code, use the marketplace commands within the Claude Code interface. This registers the DBHub MCP server and adds two specialized skills: /dbhub:setup and /dbhub:explore.

Prerequisites:

• Node.js >= 22.5.0 installed on the machine running Claude Code.
• The database must be network-reachable from the machine running Claude Code (e.g., via VPN or allow-list).

Installation Steps:

1. Add the DBHub marketplace: /plugin marketplace add bytebase/dbhub
2. Install the plugin: /plugin install dbhub@dbhub

During installation, Claude Code will prompt for your database connection string (DSN). This is stored in secure storage and is not saved in a config file. An example DSN is postgres://user:password@localhost:5432/dbname.

Integrate DBHub with Codex using the CLI or by editing the TOML configuration file at ~/.codex/config.toml.

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

You can create reusable, parameterized database operations that are automatically registered as MCP tools by defining a statement and parameters in the [[tools]] section.

Requirements for Custom Tools:

• name: The name of the tool.
• description: A human-readable description (required for custom tools) to help AI models understand usage.
• source: The source ID to use.
• statement: The SQL query containing placeholders (e.g., $1 for PostgreSQL, ? for MySQL/SQLite, @p1 for SQL Server).
• parameters: An array of parameter definitions matching the placeholders in the statement.

[[tools]]
name = "get_user_by_id"
description = "Retrieve user details by their unique ID"
source = "production"
statement = "SELECT id, name, email, created_at FROM users WHERE id = $1"

[[tools.parameters]]
name = "user_id"
type = "integer"
description = "The unique user ID"

The Workbench is a web-based interface for interacting with database tools, executing queries, running custom tools, and viewing request traces. To use the Workbench, you must run DBHub with the http transport.

After starting the server, access the interface by opening http://localhost:8080 in your web browser.

npx @bytebase/dbhub --transport http --port 8080 --dsn "postgres://..."

Use npx to run DBHub. This requires Node.js version 22.5.0 or higher.

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