Skip to main content
The MCP Bundle (.mcpb) is a one-click installation path — no Node.js install, no JSON config editing, and no remote HTTP endpoint or OAuth setup. It is an open format governed by the Model Context Protocol project; clients that install it directly include Claude Desktop, Claude Code, and MCP for Windows. It is the recommended way to give non-technical users curated database access.

​
Install

  1. Download dbhub-<version>.mcpb from the latest GitHub release.
  2. Install it in your client — in Claude Desktop, double-click the file (or drag it into Settings → Extensions).
  3. Enter your database connection string when prompted, e.g. postgres://user:password@host:5432/dbname. It is stored in the OS keychain, not in a config file.
The bundle includes the drivers for all supported databases and runs locally over stdio.

​
Clients without native .mcpb support

Clients like Cursor and VS Code can still run the unpacked bundle as a plain stdio MCP server. An .mcpb is a zip archive; this path needs a local Node.js >= 22.5 (native .mcpb clients ship their own runtime): 
# Unpack
unzip dbhub-<version>.mcpb -d ~/dbhub-mcpb

# Verify it runs (Ctrl-C to stop)
DBHUB_DSN="postgres://user:password@host:5432/dbname" \
  node ~/dbhub-mcpb/server/index.js --transport stdio --config ~/dbhub-mcpb/dbhub.toml
Then register it in the client’s MCP config (e.g. .cursor/mcp.json or .vscode/mcp.json), using absolute paths: 
{
  "mcpServers": {
    "dbhub": {
      "command": "node",
      "args": [
        "/home/you/dbhub-mcpb/server/index.js",
        "--transport",
        "stdio",
        "--config",
        "/home/you/dbhub-mcpb/dbhub.toml"
      ],
      "env": {
        "DBHUB_DSN": "postgres://user:password@host:5432/dbname"
      }
    }
  }
}
Note the trade-off: here the DSN lives in a config file, not the OS keychain. For these clients the npm install path (npx @bytebase/dbhub) is usually simpler — the unpacked-bundle route only makes sense when you want the bundle’s pinned, read-only configuration distributed as a single vetted artifact.

​
Read-only by design

The bundled configuration sets readonly = true and max_rows = 1000 on execute_sql: mutating statements are rejected, and the database session is additionally set to read-only at the engine level. Still, connect with a least-privilege, read-only database account — defense in depth beats configuration alone.
The machine running the MCP client connects directly to the database, so the database must be reachable from it (VPN or network allow-list). AWS IAM and Azure AD authentication are not included in the bundle; repackage with those drivers added if you need them.

​
Packaging your own bundle

To ship a different policy — multiple sources, custom tools, a baked-in DSN so users have nothing to configure — edit mcpb/dbhub.toml (and mcpb/manifest.json if you change user_config) and rebuild: 
git clone https://github.com/bytebase/dbhub.git && cd dbhub
pnpm install
# Edit mcpb/dbhub.toml (tool policy) and mcpb/manifest.json (user settings)
pnpm run build:mcpb   # produces dist-mcpb/dbhub-<version>.mcpb
pnpm run test:mcpb    # smoke-tests the packed bundle over stdio
Anything in a [[sources]] or [[tools]] section of the TOML configuration works in the bundle, including ${ENV_VAR} interpolation — the stock bundle uses dsn = "${DBHUB_DSN}", with DBHUB_DSN supplied by the client from the user’s extension settings.
If you bake a DSN into your own bundle, remember that anyone can unzip an .mcpb and read it. Only embed credentials for a curated, read-only, least-privilege account.