Dbridge MCP

dbridge-mcp

An MCP server that lets an AI agent query a SQL database in plain language — safely and read-only.

=22.5">

The agent discovers the schema on its own (list_tables, describe_table), then writes and runs a SELECT for whatever the user asks. No hand-written endpoint per question.

Works with SQLite, PostgreSQL, and MySQL / MariaDB.

Why

A raw LLM cannot know what is inside your database, and web search cannot reach private data. dbridge gives the model a guarded door to that data: it can read and answer, but it cannot write, drop, or leak the whole table.

Why dbridge and not another database MCP?

There are many database MCP servers. dbridge is built around one idea — you should be able to point an AI at a real database without holding your breath — and that shows up as a combination the single-engine servers don't offer:

• One server, three engines. SQLite, PostgreSQL, and MySQL/MariaDB behind the same tools and the same config. Switch databases by changing the connection string, not the tooling.
• Read-only twice over. A SQL guard rejects anything but SELECT/WITH *and* every query runs inside a database-enforced READ ONLY transaction — so even a query that outsmarts the guard cannot write.
• Column-level privacy. Hide columns from the model entirely, or mask values (a***@site.com) while keeping them queryable. Most servers expose whatever the connection can see.
• Blast-radius controls. Row caps enforced over user-supplied LIMITs, per-query timeouts, EXPLAIN-based cost rejection for expensive queries, per-minute rate limits, and a capped connection pool.
• No native build step. SQLite uses Node's built-in node:sqlite, so npx -y dbridge-mcp works without a compiler toolchain.
• Performance insight, not just queries. column_stats and index_health give the model real cardinality and index-usage data, and test_index simulates an index with hypopg before anyone builds it — so the model's optimization advice is grounded in the actual database instead of guesswork.

If all you need is "run SQL from my agent", plenty of servers do that. dbridge is for pointing an agent at data you actually care about.

Tools

Resources

Prompts

Requirements

Node.js 22.5+ (SQLite uses the built-in node:sqlite, no native build step).

Install

The published package ships a dbridge-mcp binary, so no clone or build step is needed to use it. Point it at a database with the connection argument:

npx -y dbridge-mcp demo.db                                  # SQLite (file path)

npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb" # PostgreSQL npx -y dbridge-mcp "mysql://user:pass@host:3306/mydb" # MySQL / MariaDB

The database engine is chosen from the connection string: a file path is SQLite, postgres:// / postgresql:// is PostgreSQL, and mysql:// is MySQL/MariaDB.

Or install it once, globally:

npm install -g dbridge-mcp

dbridge-mcp "postgresql://user:pass@host:5432/mydb"

MCP clients start the server for you as a subprocess — see the client sections below.

Windows note: MCP clients cannot launch npx directly on Windows because it is a .cmd script. Wrap it with cmd /c — use "command": "cmd" and put "/c", "npx", "-y", "dbridge-mcp", " " in the args. The examples below use the direct form (macOS/Linux); on Windows add the cmd /c prefix.

Use it in Claude Desktop

Claude Desktop only supports a single global config. Add to claude_desktop_config.json:

{

"mcpServers": { "dbridge": { "command": "npx", "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"], "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" } } } }

For a local SQLite file, replace the connection string with an absolute path to the .db file. Restart Claude Desktop, then ask: _"what were the 5 best-selling products last month?"_

Use it in Claude Code

Add it to the current project with the CLI:

claude mcp add dbridge --scope project \

-e DBRIDGE_CONFIG=/absolute/path/to/dbridge.config.json \ -- npx -y dbridge-mcp "postgresql://user:pass@host:5432/mydb"

--scope project writes a shareable .mcp.json in the project root; use --scope user for a global server or omit it for a private per-project one. The .mcp.json looks like:

{

"mcpServers": { "dbridge": { "command": "npx", "args": ["-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"], "env": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" } } } }

Run claude from that directory; approve the project server once, then check it with /mcp.

Use it in Cursor

Add the same mcpServers block to .cursor/mcp.json in the project root (or ~/.cursor/mcp.json for all projects), enable the server under Settings → MCP, then ask the Agent a question about your data.

Use it in Windsurf

Add the same mcpServers block to ~/.codeium/windsurf/mcp_config.json, then refresh the server list under Settings → Cascade → MCP.

Use it in OpenCode

Add to opencode.json (project root or ~/.config/opencode/opencode.json):

{

"$schema": "https://opencode.ai/config.json", "mcp": { "dbridge": { "type": "local", "command": ["npx", "-y", "dbridge-mcp", "postgresql://user:pass@host:5432/mydb"], "enabled": true } } }

To tune the safety guard, point the server at a config file with the environment block:

"environment": { "DBRIDGE_CONFIG": "/absolute/path/to/dbridge.config.json" }

Docker

Build the image and run the server over stdio:

docker build -t dbridge-mcp .

docker run --rm -i dbridge-mcp "postgresql://user:pass@host:5432/mydb"

Mount a config file and point DBRIDGE_CONFIG at it:

docker run --rm -i \

-v "$PWD/dbridge.config.json:/config.json:ro" \ -e DBRIDGE_CONFIG=/config.json \ dbridge-mcp "postgresql://user:pass@host:5432/mydb"

Safety

• The connection is opened read-only. On PostgreSQL and MySQL every query also runs inside a READ ONLY transaction, so writes are rejected by the database itself even if a query slips past the guard.
• Only SELECT and WITH statements pass; writes, DDL, and data-modifying CTEs are rejected.
• A single statement per call; the row cap is enforced even when a query supplies its own larger LIMIT (default 1000 rows).
• Each PostgreSQL and MySQL query is bounded by a per-query timeout (statement_timeout / max_execution_time), so a runaway or expensive query cannot pin the database.
• System catalogs and credential tables (information_schema, pg_authid, sqlite_master, …) are not queryable; schema discovery goes through the tools.
• Restricted columns can be hidden entirely: the model cannot see them in the schema, query them, or receive them in results.
• Tables can be restricted with an allow-list or block-list; blocked tables are invisible and unqueryable.
• Columns can be masked instead of hidden: they stay visible but values come back partially redacted (e.g. a***@site.com).
• Expensive queries can be rejected up front by an EXPLAIN cost estimate, and callers can be rate-limited per minute.
• The connection pool size is capped, so dbridge cannot exhaust the database's connections.

Config

Every setting has three sources, in increasing precedence: a JSON file (DBRIDGE_CONFIG), environment variables, then CLI flags. So you can drop the JSON file entirely and set only what you need:

npx -y dbridge-mcp "postgresql://user:pass@host/db" --max-rows 200 --statement-timeout-ms 3000 --masked-columns email,iban

DBRIDGE_MAX_ROWS=200 DBRIDGE_REQUIRE_SSL=true npx -y dbridge-mcp "postgresql://user:pass@host/db"

Or keep everything in one place: point DBRIDGE_CONFIG at a JSON file (see dbridge.config.example.json for a full template). Every field is optional:

{

"maxRows": 500, "hiddenColumns": ["ssn", "password_hash"], "maskedColumns": ["iban", { "column": "email", "strategy": "email" }], "allowedTables": ["products", "sales", "customers"], "blockedTables": ["employees", "audit_log"], "statementTimeoutMs": 5000, "maxCost": 100000, "rateLimitPerMin": 60, "maxPoolSize": 5, "connectionTimeoutMs": 10000, "requireSsl": true, "schemas": ["public", "reporting"], "auditLog": true }

| statementTimeoutMs | --statement-timeout-ms / DBRIDGE_STATEMENT_TIMEOUT_MS | 10000 | Per-query timeout (PostgreSQL statement_timeout, MySQL max_execution_time