Provides Docker container deployment options for running the DBHub server with configurable database connections and transport options.
Supports connecting to DuckDB databases to explore tables, access schema information, and perform read-only SQL queries with safety measures.
Provides access to MySQL databases for browsing tables, viewing schema information, and executing read-only SQL queries with safety protections.
Allows querying PostgreSQL databases, browsing tables, viewing schema information, and running read-only SQL queries with safety checks.
Enables connection to SQLite databases to browse available tables, view schema information, and run protected read-only SQL queries.
Note
Brought to you by Bytebase, open-source database DevSecOps platform.
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.
Demo HTTP Endpoint
https://demo.dbhub.ai/message connects a sample employee database. You can point Cursor or MCP Inspector to it to see it in action.
Supported Matrix
Database Resources
Resource Name | URI Format | PostgreSQL | MySQL | MariaDB | SQL Server | SQLite |
---|---|---|---|---|---|---|
schemas | db://schemas | ✅ | ✅ | ✅ | ✅ | ✅ |
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_details_in_schema | db://schemas/{schemaName}/procedures/{procedureName} | ✅ | ✅ | ✅ | ✅ | ❌ |
Database Tools
Tool | Command Name | Description | PostgreSQL | MySQL | MariaDB | SQL Server | SQLite |
---|---|---|---|---|---|---|---|
Execute SQL | execute_sql | Execute single or multiple SQL statements (separated by semicolons) | ✅ | ✅ | ✅ | ✅ | ✅ |
Prompt Capabilities
Prompt | Command Name | PostgreSQL | MySQL | MariaDB | SQL Server | SQLite |
---|---|---|---|---|---|---|
Generate SQL | generate_sql | ✅ | ✅ | ✅ | ✅ | ✅ |
Explain DB Elements | explain_db | ✅ | ✅ | ✅ | ✅ | ✅ |
Installation
Docker
NPM
Note: The demo mode includes a bundled SQLite sample "employee" database with tables for employees, departments, salaries, and more.
Claude Desktop
- Claude Desktop only supports
stdio
transport https://github.com/orgs/modelcontextprotocol/discussions/16
Claude Code
Check https://docs.anthropic.com/en/docs/claude-code/mcp
Cursor
- Cursor supports both
stdio
andhttp
. - Follow Cursor MCP guide and make sure to use Agent mode.
Usage
Read-only Mode
You can run DBHub in read-only mode, which restricts SQL query execution to read-only operations:
In read-only mode, only readonly SQL operations are allowed.
This provides an additional layer of security when connecting to production databases.
SSL Connections
You can specify the SSL mode using the sslmode
parameter in your DSN string:
Database | sslmode=disable | sslmode=require | Default SSL Behavior |
---|---|---|---|
PostgreSQL | ✅ | ✅ | Certificate verification |
MySQL | ✅ | ✅ | Certificate verification |
MariaDB | ✅ | ✅ | Certificate verification |
SQL Server | ✅ | ✅ | Certificate verification |
SQLite | ❌ | ❌ | N/A (file-based) |
SSL Mode Options:
sslmode=disable
: All SSL/TLS encryption is turned off. Data is transmitted in plaintext.sslmode=require
: Connection is encrypted, but the server's certificate is not verified. This provides protection against packet sniffing but not against man-in-the-middle attacks. You may use this for trusted self-signed CA.
Without specifying sslmode
, most databases default to certificate verification, which provides the highest level of security.
Example usage:
SSH Tunnel Support
DBHub supports connecting to databases through SSH tunnels, enabling secure access to databases in private networks or behind firewalls.
Using SSH Config File (Recommended)
DBHub can read SSH connection settings from your ~/.ssh/config
file. Simply use the host alias from your SSH config:
DBHub will automatically use the settings from your SSH config, including hostname, user, port, and identity file. If no identity file is specified in the config, DBHub will try common default locations (~/.ssh/id_rsa
, ~/.ssh/id_ed25519
, etc.).
SSH with Password Authentication
SSH with Private Key Authentication
SSH with Private Key and Passphrase
Using Environment Variables
Note: When using SSH tunnels, the database host in your DSN should be the hostname/IP as seen from the SSH server (bastion host), not from your local machine.
Configure your database connection
You can use DBHub in demo mode with a sample employee database for testing:
Warning
If your user/password contains special characters, you need to escape them first. (e.g. pass#word
should be escaped as pass#word
)
For real databases, a Database Source Name (DSN) is required. You can provide this in several ways:
- Command line argument (highest priority):
- Environment variable (second priority):
- Environment file (third priority):
- For development: Create
.env.local
with your DSN - For production: Create
.env
with your DSN
- For development: Create
Warning
When running in Docker, use host.docker.internal
instead of localhost
to connect to databases running on your host machine. For example: mysql://user:password@host.docker.internal:3306/dbname
DBHub supports the following database connection string formats:
Database | DSN Format | Example |
---|---|---|
MySQL | mysql://[user]:[password]@[host]:[port]/[database] | mysql://user:password@localhost:3306/dbname?sslmode=disable |
MariaDB | mariadb://[user]:[password]@[host]:[port]/[database] | mariadb://user:password@localhost:3306/dbname?sslmode=disable |
PostgreSQL | postgres://[user]:[password]@[host]:[port]/[database] | postgres://user:password@localhost:5432/dbname?sslmode=disable |
SQL Server | sqlserver://[user]:[password]@[host]:[port]/[database] | sqlserver://user:password@localhost:1433/dbname?sslmode=disable |
SQLite | sqlite:///[path/to/file] or sqlite:///:memory: | sqlite:///path/to/database.db , sqlite:C:/Users/YourName/data/database.db (windows) or sqlite:///:memory: |
SQL Server
Extra query parameters:
authentication
authentication=azure-active-directory-access-token
. Only applicable when running from Azure. See DefaultAzureCredential.
Transport
- stdio (default) - for direct integration with tools like Claude Desktop:
- http - for browser and network clients:
Command line options
Option | Environment Variable | Description | Default |
---|---|---|---|
dsn | DSN | Database connection string | Required if not in demo mode |
transport | TRANSPORT | Transport mode: stdio or http | stdio |
port | PORT | HTTP server port (only applicable when using --transport=http ) | 8080 |
readonly | READONLY | Restrict SQL execution to read-only operations | false |
demo | N/A | Run in demo mode with sample employee database | false |
ssh-host | SSH_HOST | SSH server hostname for tunnel connection | N/A |
ssh-port | SSH_PORT | SSH server port | 22 |
ssh-user | SSH_USER | SSH username | N/A |
ssh-password | SSH_PASSWORD | SSH password (for password authentication) | N/A |
ssh-key | SSH_KEY | Path to SSH private key file | N/A |
ssh-passphrase | SSH_PASSPHRASE | Passphrase for SSH private key | N/A |
The demo mode uses an in-memory SQLite database loaded with the sample employee database that includes tables for employees, departments, titles, salaries, department employees, and department managers. The sample database includes SQL scripts for table creation, data loading, and testing.
Development
- Install dependencies:
- Run in development mode:
- Build for production:
Testing
The project uses Vitest for comprehensive unit and integration testing:
- Run all tests:
pnpm test
- Run tests in watch mode:
pnpm test:watch
- Run integration tests:
pnpm test:integration
Integration Tests
DBHub includes comprehensive integration tests for all supported database connectors using Testcontainers. These tests run against real database instances in Docker containers, ensuring full compatibility and feature coverage.
Prerequisites
- Docker: Ensure Docker is installed and running on your machine
- Docker Resources: Allocate sufficient memory (recommended: 4GB+) for multiple database containers
- Network Access: Ability to pull Docker images from registries
Running Integration Tests
Note: This command runs all integration tests in parallel, which may take 5-15 minutes depending on your system resources and network speed.
All integration tests follow these patterns:
- Container Lifecycle: Start database container → Connect → Setup test data → Run tests → Cleanup
- Shared Test Utilities: Common test patterns implemented in
IntegrationTestBase
class - Database-Specific Features: Each database includes tests for unique features and capabilities
- Error Handling: Comprehensive testing of connection errors, invalid SQL, and edge cases
Troubleshooting Integration Tests
Container Startup Issues:
SQL Server Timeout Issues:
- SQL Server containers require significant startup time (3-5 minutes)
- Ensure Docker has sufficient memory allocated (4GB+ recommended)
- Consider running SQL Server tests separately if experiencing timeouts
Network/Resource Issues:
Pre-commit Hooks (for Developers)
The project includes pre-commit hooks to run tests automatically before each commit:
- After cloning the repository, set up the pre-commit hooks:
- This ensures the test suite runs automatically whenever you create a commit, preventing commits that would break tests.
Debug with MCP Inspector
stdio
HTTP
Connect to the DBHub server /message
endpoint
Contributors
Star History
This server cannot be installed
remote-capable server
The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.
Universal database MCP server connecting to MySQL, PostgreSQL, SQLite, DuckDB and etc.
Related Resources
Related MCP Servers
- -securityAlicense-qualityMCP to access any database accessible via JDBC such as Postgres, Oracle, mysql, mariadb, sqlite etc.Last updated -163Apache 2.0
- -securityAlicense-qualityAn MCP server that connects to Supabase PostgreSQL databases, exposing table schemas as resources and providing tools for data analysis through SQL queries.Last updated -1JavaScriptMIT License
- -securityAlicense-qualityMCP-Server from your Database optimized for LLMs and AI-Agents. Supports PostgreSQL, MySQL, ClickHouse, Snowflake, MSSQL, BigQuery, Oracle Database, SQLite, ElasticSearch, DuckDBLast updated -448GoApache 2.0
- -securityAlicense-qualityOpen source MCP server specializing in easy, fast, and secure tools for Databases.Last updated -9,413GoApache 2.0