Skip to content
bytebasePublic

About

Token conscious database MCP server for Postgres, MySQL, SQL Server, Oracle, MariaDB, SQLite, ClickHouse.

Topics

Resources

Stars

3.9k stars

Watchers

21 watching

Forks

Latest commit

 

History

759 Commits

Folders and files

NameName
Last commit message
Last commit date
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 
 

Repository files navigation

Note

If you need an enterprise-level database MCP server with built-in guardrails like approval flow, access control, data masking, and audit logging beyond what DBHub offers, check out Bytebase.

Featured in the official Claude Code docs — read the DBHub example

DBHub Logo

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

DBHub is a minimal MCP server: token-efficient, zero-dependency, and just two tools by default with opt-in extras. This lightweight gateway allows MCP-compatible clients to connect to and explore different databases:

  • Minimal: Zero dependency, token efficient with a minimal set of MCP tools to maximize context window
  • Multi-Database: PostgreSQL, MySQL, MariaDB, SQL Server, Oracle, ClickHouse, 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

Our community includes developers from 30 companies and 10 universities, including Microsoft, NVIDIA, Amazon, Google, Oxford, Cornell, Duke, Tsinghua, Peking, KAIST, UBC, and Waseda.

Token Efficiency

DBHub's two built-in tool definitions total 261 tokens with the cl100k_base tokenizer.

MCP Server Definition Tokens Tools
DBHub 2.0.1 261 2
MCP Toolbox 1.18.0 3,901 29
Supabase MCP 0.19.0 6,982 36

Full tool definitions, not session usage. See the November 2026 benchmark for configurations and reproduction steps.

Use Cases

  • Local Development: Schema exploration, query validation, and data debugging with Claude Code, VS Code, Cursor, etc.
  • Non-Technical Access: Expose curated, read-only views to non-technical staff via Claude Desktop, VS Code, Cursor, etc.
  • Multi-Database Consolidation: Replace separate MCP servers for each database with a single DBHub process
  • Production Troubleshooting: Read-only diagnostics with guardrails against runaway queries

Read-only mode is a guardrail, not a permission boundary. Always connect with a least-privilege, read-only database user. See Read-Only Mode.

Supported Databases

PostgreSQL, MySQL, SQL Server, MariaDB, Oracle, ClickHouse, 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
  • explain_sql (opt-in): Show a query's execution plan without running it
  • health_check (opt-in): Report connection pool state and buffer cache hit ratio
  • 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 overview

DBHub Workbench showing connection details and available tools
Execute SQL

SQL editor showing an employee query and its results
Request traces

Recent SQL requests with execution times and client details

Installation

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

For Claude Code, install the plugin:

/plugin marketplace add bytebase/dbhub
/plugin install dbhub@dbhub

For Codex, install the plugin (reads the connection string from DBHUB_DSN):

codex plugin marketplace add bytebase/dbhub
codex plugin add dbhub@dbhub

Also available as:

See the Installation Guide for all options, Command-Line Options for parameters, and Multi-Database Configuration for connecting several databases at once.

Replacing @modelcontextprotocol/server-postgres

The reference PostgreSQL MCP server, @modelcontextprotocol/server-postgres, is archived and marked deprecated on npm ("Archived and unmaintained; no security guarantees"). DBHub is a maintained replacement. Swap the package and pass the connection string with --dsn; an existing postgresql:// URL works unchanged.

Before:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "postgresql://localhost/mydb"]
    }
  }
}

After:

{
  "mcpServers": {
    "dbhub": {
      "command": "npx",
      "args": ["-y", "@bytebase/dbhub@latest", "--dsn", "postgresql://localhost/mydb"]
    }
  }
}

The old server only ran read-only queries. With --dsn alone, DBHub's execute_sql can also write. To keep it read-only, point --config at a TOML file that sets readonly = true. The replacement guide has that config and the other differences.

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.

See the branding guide for logo assets, the Zinc color theme, and the asset sync workflow.

Contributors

Star History

Star History Chart

About

Token conscious database MCP server for Postgres, MySQL, SQL Server, Oracle, MariaDB, SQLite, ClickHouse.

Topics

Resources

Stars

3.9k stars

Watchers

21 watching

Forks

Releases

Packages

Used by

Contributors

Languages