dbridge-mcp

Purpose

dbridge-mcp is an MCP server that lets AI agents query SQL databases in natural language, securely and read-only. A raw LLM cannot know what is in a database, and web search cannot access private data; dbridge gives the model a guarded door: the model can read and answer questions, but cannot write, delete, or leak an entire table. The agent discovers the schema on its own (via list_tables, describe_table), then writes and runs SELECTs for the user's questions, with no need to hand-write an endpoint for every question.

Supported engines

The same server supports three engines: SQLite, PostgreSQL, and MySQL/MariaDB, using the same tools and configuration. The engine is determined by the connection string: a file path is SQLite, postgres:// or postgresql:// is PostgreSQL, and mysql:// is MySQL/MariaDB. Switching databases only requires changing the connection string, not changing tools.

Main capabilities

• Double read-only safeguard: the SQL guard rejects any statement other than SELECT/WITH, and every query runs in a database-enforced READ ONLY transaction, so even a query that bypasses the guard cannot write.
• Column-level privacy: columns can be fully hidden (the model cannot see them in the schema, cannot query them, and they are absent from results), or values can be masked (e.g. a***@site.com) while still being queryable.
• Blast-radius control: enforces a row limit (default cap of 1000 rows even if the query itself has a larger LIMIT), a per-query timeout, EXPLAIN-based cost rejection of expensive queries, a per-minute rate limit, and a restricted connection pool.
• No native build step: SQLite uses Node's built-in node:sqlite, so npx -y dbridge-mcp requires no compiler toolchain.
• Performance insight: column_stats and index_health provide real cardinality and index usage data, and test_index can simulate an index with hypopg before deciding whether to create it, letting the model base optimization advice on the actual database rather than guesses.

Usage

Requires Node.js 22.5+. The published package ships with the dbridge-mcp binary, so there is no need to clone or build. Via the connection parameterpoint it at the database: npx -y dbridge-mcp <connection>. It can also be installed globally once.

MCP clients start the server as a child process. Claude Desktop requires adding configuration in claude_desktop_config.json; Claude Code can add it via CLI (--scope project writes to .mcp.json, --scope user is global); Cursor requires adding an mcpServers block in .cursor/mcp.json; Windsurf adds it in ~/.codeium/windsurf/mcp_config.json; OpenCode adds it in opencode.json. On Windows, since npx is a .cmd script, it must be wrapped with cmd /c, using "command": "cmd" and placing "/c", "npx", "-y", "dbridge-mcp", "<connection>" in args.

The security guard can also be adjusted by pointing the DBRIDGE_CONFIG environment variable at a JSON configuration file. All settings have three sources, in order of increasing priority: JSON file, environment variables, CLI flags. List values on the command line or in environment variables are comma-separated (e.g. --allowed-tables products,sales).

Use cases

• Pointing AI agents at real data that needs protection, for example having the agent answer "What were the 5 best-selling products last month?".
• Running on production databases: it is recommended to pass the connection string via the DBRIDGE_DB_PATH environment variable to avoid passwords appearing in the process list; use a dedicated database role with read-only grants only on the target tables; set conservative statementTimeoutMs, maxRows, and maxCost, and expose only reporting tables with allowedTables.
• Local development and debugging: the repository can be cloned and built from source, and used with MCP Inspector to test tools without an LLM or API key.

Limitations

• Only one statement is allowed per call, and the row cap is always in effect.
• System catalogs and credential tables (information_schema, pg_authid, sqlite_master, etc.) cannot be queried; schema discovery must be done through tools.
• tables can be restricted via an allowlist or blocklist; blocked tables are invisible and cannot be queried.
• Masked columns can still be used in WHERE/GROUP BY; true secrets should use hiddenColumns, and values that need to be identifiable but not exposed should use maskedColumns.
• run_query and sample_table support an optional format parameter: json (default full result object), csv, or markdown; the latter two return a compact table with a brief rows: N · Nms header, and can be combined with maxCellChars and maxResultBytes to control large results.
• Engine notes: statementTimeoutMs, maxCost, maxPoolSize, connectionTimeoutMs, requireSsl, and schemas apply to network engines (PostgreSQL/MySQL); SQLite is a local file and ignores these settings; row limits, column/table access control, and masking apply to all engines.