querybridge-mcp

library0.11.1jsnpmunverified

A Model Context Protocol (MCP) server connecting Claude Code and other MCP clients to MySQL/MariaDB databases. Version 0.11.1 (2025) is stable, with active development on GitHub. It provides 39 tools across schema introspection, querying, profiling, ERD generation, stored programmability, diagnostics, and cross-database diffing, plus 2 resources and 4 prompts. Key differentiators vs alternatives: built-in SSH tunnel with host fingerprint pinning, SSL/TLS support, read-only-by-default with per-connection write control, client-side blocking of LOAD DATA LOCAL INFILE, secrets via env/file indirection, MCP signal cancellation mapping to KILL QUERY, and a CLI for managing connections. Ships TypeScript types, requires Node >=20, and supports both local stdio and remote Streamable HTTP transport with bearer auth.

database devops

npm install querybridge-mcp

github ↗package ↗homepage ↗

INSTALL

IMPORT

SIG · QUERYBRIDGE-MCP

querybridge-mcp

databasejavascriptv0.11.1

harness data pending

Install & Compatibility

Where this runs

No compatibility data collected yet for this library.

Code

Verified usage

Verified import paths — ran on the pinned version, not inferred.

Server

✓ import { Server } from 'querybridge-mcp'

✗ const Server = require('querybridge-mcp').Server

Package is ESM-only; named export for the MCP server class. TypeScript types included.

connectMySQL

✓ import { connectMySQL } from 'querybridge-mcp'

✗ import connectMySQL from 'querybridge-mcp'

Default export does not exist; always use named import.

Config

✓ import type { Config } from 'querybridge-mcp'

✗ import { Config } from 'querybridge-mcp'

Config is a TypeScript interface; use 'import type' for type-only imports. If using as value (unlikely), named import works.

Shows basic setup of querybridge-mcp server with a single MySQL connection in read-only mode, using environment variables for credentials.

// Start the MCP server with stdio transport (for Claude Code) import { Server } from 'querybridge-mcp'; const server = new Server({ connections: [ { name: 'my-db', host: process.env.MYSQL_HOST ?? 'localhost', port: Number(process.env.MYSQL_PORT ?? 3306), user: process.env.MYSQL_USER ?? 'root', password: process.env.MYSQL_PASSWORD ?? '', database: process.env.MYSQL_DATABASE ?? 'test', readOnly: true, // enforce read-only }, ], }); await server.start(); /* // Alternatively, run via CLI: // npx querybridge-mcp --config my-config.json */

Debug

Known issues

breakingThe package requires Node.js >=20. Older versions will throw a runtime error.

fix

Upgrade Node.js to v20 or later.

affects: <0.11

deprecatedInline plaintext passwords in config are deprecated; use { env: 'VAR_NAME' } or { file: '/path/to/secret' } instead.

fix

Migrate to secrets indirection: password: { env: 'MYSQL_PASSWORD' }.

affects: >=0.10

gotchaSSH host fingerprints are pinned by default. If the remote host key changes, connections fail unless you update the fingerprint in config.

fix

Set ssh.fingerprint to 'ignore' (not recommended) or update the stored fingerprint.

affects: >=0.11

breakingThe 'mysql2' module is bundled; do not install it separately or version conflicts may arise.

fix

Remove mysql2 from your dependencies; querybridge-mcp uses its own bundled version.

affects: >=0.10

gotchaRead-only mode is enforced by server-side SET SESSION transaction_read_only=ON. Some MySQL users (e.g., Amazon RDS admin) may not have permission to set session variables, causing errors.

fix

Set readOnly: false for that connection, or grant the 'SESSION_VARIABLES_ADMIN' privilege.

affects: >=0.11

Errors

Common errors & fixes

Error: Cannot find module 'querybridge-mcp'

Package not installed or import path wrong (e.g., trying to require in CJS).

fix

npm install querybridge-mcp --save; ensure your project uses ESM (type: 'module' in package.json) or use dynamic import() if locked into CJS.

Error: connect ECONNREFUSED 127.0.0.1:3306

MySQL server not running or wrong host/port (common when using SSH tunnel without proper forwarding).

fix

Verify MySQL is running: mysql -u root -p -h 127.0.0.1. For SSH tunnels, check the tunnel is established and the local port matches the one in config.

TypeError: (0 , querybridge_mcp.Server) is not a function

Importing default export instead of named export (Server).

fix

Use: import { Server } from 'querybridge-mcp' (not: import Server from 'querybridge-mcp').

Error: read-only mode not allowed: user lacks privilege to set transaction_read_only

MySQL user does not have SESSION_VARIABLES_ADMIN or equivalent privilege.

fix

Set readOnly: false in config for that connection, or GRANT SESSION_VARIABLES_ADMIN ON *.* TO 'user'@'host';

Error: SSH host key mismatch

Remote server's host key changed; fingerprint pinned in config no longer matches.

fix

Update the 'fingerprint' field in the SSH config to the new host key, or set to 'ignore' (insecure).

Upgrade

Version history

0.11.1latest on npm

Audit

Dependencies

mysql2requiredunderlying MySQL/MariaDB driver used for all database connections and queries

ssh2optionalSSH tunnel support; optional if not using SSH connections

@modelcontextprotocol/sdkrequiredMCP SDK for server implementation and protocol compliance

Agent activity

11 hits · last 30 days

node

Resources

githubhttps://github.com/MahmoudHassanMustafa/querybridge-mcp ↗

packagequerybridge-mcp ↗

homepagehttps://github.com/MahmoudHassanMustafa/querybridge-mcp#readme ↗