> ## Documentation Index
> Fetch the complete documentation index at: https://dbhub.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# MCP Bundle

> One-click, read-only install via .mcpb for Claude Desktop and other MCPB clients

The [MCP Bundle](https://github.com/modelcontextprotocol/mcpb) (`.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](https://github.com/bytebase/dbhub/releases/latest).
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):

```bash theme={null}
# 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:

```json theme={null}
{
  "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](/installation) (`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.

<Note>
  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.
</Note>

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

```bash theme={null}
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](/config/toml) 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.

<Warning>
  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.
</Warning>