MCP Db Bridge

🚀 mcp-db-bridge

MCP (Model Context Protocol) server for MySQL, PostgreSQL & SQLite. It features granular permissions, multi-DB support, and cloud-ready SSL/TLS. Built with the adapter pattern for extensibility, it provides a flexible and secure solution for database management.

🚀 Quick Start

Local Database Setup

MySQL

# .env
DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=mydb

PostgreSQL

# .env
DB_TYPE=postgresql
DB_HOST=127.0.0.1
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=mydb

SQLite (In-Memory)

# .env
DB_TYPE=sqlite
SQLITE_DB=:memory:

Run the Server

pnpm build
pnpm start
# or
node dist/index.js

✨ Features

• 🔌 Multi-Database: Support for MySQL, PostgreSQL, and SQLite.
• 🏗️ Adapter Pattern: Clean and extensible architecture.
• ☁️ Cloud-Ready: SSL/TLS support for AWS RDS, Google Cloud SQL, and Azure Database.
• 🔒 Security First: Read-only mode and granular schema permissions.
• 🌐 Multi-DB Mode: Simultaneous access to multiple schemas/databases.
• 🔄 Transactions: Automatic BEGIN/COMMIT/ROLLBACK.
• 🚀 HTTP Mode: Optional remote HTTP server (Express).

📦 Installation

npm install mcp-db-bridge
# or
pnpm add mcp-db-bridge

💻 Usage Examples

MySQL with Unix Socket

DB_TYPE=mysql
MYSQL_SOCKET_PATH=/tmp/mysql.sock
DB_USER=root
DB_PASS=password
DB_NAME=mydb

PostgreSQL Multi-DB with Permissions

DB_TYPE=postgresql
DB_HOST=localhost
DB_PORT=5432
DB_USER=postgres
DB_PASS=password
DB_NAME=                                      # Multi-DB mode
SCHEMA_INSERT_PERMISSIONS=app_db:true         # app_db can insert
SCHEMA_UPDATE_PERMISSIONS=app_db:true         # app_db can update
SCHEMA_DELETE_PERMISSIONS=app_db:false        # app_db: DELETE blocked

SQLite Read-Only

DB_TYPE=sqlite
SQLITE_DB=/var/lib/data/production.db
DB_READ_ONLY_MODE=true

AWS RDS MySQL with SSL

DB_TYPE=mysql
DB_HOST=prod.abc123.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_USER=admin
DB_PASS=secure_password
DB_NAME=production
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true
ALLOW_INSERT_OPERATION=false
ALLOW_UPDATE_OPERATION=false
ALLOW_DELETE_OPERATION=false
ALLOW_DDL_OPERATION=false

📚 Documentation

Configuration

Database Types

DB_TYPE=mysql          # MySQL
DB_TYPE=postgresql     # PostgreSQL
DB_TYPE=sqlite         # SQLite

Connection Settings

Generic (All Databases)

DB_HOST=127.0.0.1
DB_PORT=3306           # MySQL: 3306, PostgreSQL: 5432
DB_USER=root
DB_PASS=password
DB_NAME=mydb           # Leave empty for multi-DB mode
DB_CONNECTION_LIMIT=10

MySQL-Specific (Backward Compatibility)

MYSQL_HOST=127.0.0.1
MYSQL_PORT=3306
MYSQL_USER=root
MYSQL_PASS=password
MYSQL_DB=mydb
MYSQL_SOCKET_PATH=/tmp/mysql.sock  # Unix socket (priority over host/port)

PostgreSQL-Specific

POSTGRESQL_HOST=127.0.0.1
POSTGRESQL_PORT=5432
POSTGRESQL_DB=mydb

SQLite-Specific

SQLITE_DB=:memory:              # In-memory database
SQLITE_DB=/var/lib/app/data.db  # File-based database

Security & Permissions

Read-Only Mode

Blocks all write operations at the application level:

DB_READ_ONLY_MODE=true

Global Write Permissions

Fine-grained operation control by type (applied globally):

ALLOW_INSERT_OPERATION=true   # Allow INSERT
ALLOW_UPDATE_OPERATION=true   # Allow UPDATE
ALLOW_DELETE_OPERATION=false  # Block DELETE
ALLOW_DDL_OPERATION=false     # Block CREATE/ALTER/DROP/TRUNCATE

Schema-Specific Permissions

Override global permissions for specific schemas:

# Format: "schema1:true,schema2:false,schema3:true"
SCHEMA_INSERT_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_UPDATE_PERMISSIONS=prod_db:false,test_db:true,staging_db:true
SCHEMA_DELETE_PERMISSIONS=prod_db:false,test_db:false,staging_db:false
SCHEMA_DDL_PERMISSIONS=prod_db:false,test_db:true,staging_db:false

How it works:

• If a schema has specific permission → use it.
• Otherwise → use the global flag. Example:

# Global: INSERT blocked
ALLOW_INSERT_OPERATION=false

# test_db can insert, prod_db cannot
SCHEMA_INSERT_PERMISSIONS=test_db:true,prod_db:false

# Result:
# - INSERT on test_db: ✅ allowed (schema permission)
# - INSERT on prod_db: ❌ blocked (schema permission)
# - INSERT on other_db: ❌ blocked (global permission)

Multi-DB Mode

Access multiple databases/schemas through a single connection.

Activation

Leave DB_NAME empty (MySQL/PostgreSQL only):

DB_TYPE=mysql
DB_HOST=127.0.0.1
DB_PORT=3306
DB_USER=root
DB_PASS=password
DB_NAME=                # Empty = multi-DB mode

Write Protection

By default, multi-DB mode is read-only for security. To allow writes:

MULTI_DB_WRITE_MODE=true  # ⚠️ Use with caution!

Recommendation: Use SCHEMA_*_PERMISSIONS for granular control instead of MULTI_DB_WRITE_MODE=true.

Complete Example

# Multi-DB with granular permissions
DB_TYPE=mysql
DB_NAME=                                    # Multi-DB mode
ALLOW_INSERT_OPERATION=false                # Global: blocked
SCHEMA_INSERT_PERMISSIONS=test_db:true      # Exception: test_db can insert
SCHEMA_UPDATE_PERMISSIONS=test_db:true      # Exception: test_db can update
SCHEMA_DELETE_PERMISSIONS=test_db:false     # test_db: DELETE blocked
SCHEMA_DDL_PERMISSIONS=test_db:true         # test_db: DDL allowed

SSL/TLS for Cloud Databases

AWS RDS (MySQL/PostgreSQL)

DB_TYPE=mysql
DB_HOST=myinstance.123456789012.us-east-1.rds.amazonaws.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true
# Optional: DB_SSL_CA=/path/to/aws-rds-ca-cert.pem

Google Cloud SQL (PostgreSQL)

DB_TYPE=postgresql
DB_HOST=34.123.45.67
DB_PORT=5432
DB_SSL=true
DB_SSL_CA=/path/to/server-ca.pem
DB_SSL_CERT=/path/to/client-cert.pem
DB_SSL_KEY=/path/to/client-key.pem

Azure Database for MySQL

DB_TYPE=mysql
DB_HOST=myserver.mysql.database.azure.com
DB_PORT=3306
DB_SSL=true
DB_SSL_REJECT_UNAUTHORIZED=true

Remote MCP (HTTP Server)

Run the MCP server via HTTP with authentication:

# .env
IS_REMOTE_MCP=true
REMOTE_SECRET_KEY=your-secret-key-here
PORT=3000

Endpoint: POST http://localhost:3000/mcp Header: Authorization: Bearer your-secret-key-here

🔧 Technical Details

Architecture

src/
├── db/
│   ├── adapters/
│   │   ├── types.ts              # Interfaces and types
│   │   ├── factory.ts            # Factory pattern
│   │   ├── mysql.adapter.ts      # MySQL via mysql2
│   │   ├── postgresql.adapter.ts # PostgreSQL via pg
│   │   └── sqlite.adapter.ts     # SQLite via better-sqlite3
│   ├── index.ts                  # Core query handlers
│   ├── utils.ts                  # SQL parsing (node-sql-parser)
│   └── permissions.ts            # Schema permission checks
├── config/
│   └── index.ts                  # Environment configuration
├── utils/
│   └── index.ts                  # Logging & utilities
└── types/
    └── index.ts                  # Type definitions

Adapter Pattern

Each adapter implements the DatabaseAdapter interface:

export interface DatabaseAdapter {
  readonly type: DatabaseType;
  createPool(config: ConnectionConfig): Promise<DatabasePool>;
  executeQuery<T>(pool: DatabasePool, sql: string, params?: any[]): Promise<T>;
  setReadOnly(connection: DatabaseConnection): Promise<void>;
  unsetReadOnly(connection: DatabaseConnection): Promise<void>;
  normalizeResult(result: any): NormalizedResult;
  supportsReadOnlyMode(): boolean;
}

Transaction Flows

Read Operations:

BEGIN → SET TRANSACTION READ ONLY → QUERY → ROLLBACK → RESET TO READ WRITE

Write Operations:

BEGIN → QUERY → COMMIT (or ROLLBACK on error)

📄 License

This project is licensed under the MIT License.

Credits

• mcp-server-mysql: @benborla