Multi Database MCP Server
Overview
The DB MCP Server provides a standardized way for AI models to interact with multiple databases simultaneously. Built on the FreePeak/cortex framework, it enables AI assistants to execute SQL queries, manage transactions, explore schemas, and analyze performance across different database systems through a unified interface.
Core Concepts
Multi-Database Support
Unlike traditional database connectors, DB MCP Server can connect to and interact with multiple databases concurrently:
{
"connections": [
{
"id": "mysql1",
"type": "mysql",
"host": "localhost",
"port": 3306,
"name": "db1",
"user": "user1",
"password": "password1"
},
{
"id": "postgres1",
"type": "postgres",
"host": "localhost",
"port": 5432,
"name": "db2",
"user": "user2",
"password": "password2"
},
{
"id": "oracle1",
"type": "oracle",
"host": "localhost",
"port": 1521,
"service_name": "XEPDB1",
"user": "user3",
"password": "password3"
}
]
}Dynamic Tool Generation
For each connected database, the server automatically generates specialized tools:
// For a database with ID "mysql1", these tools are generated:
query_mysql1 // Execute SQL queries
execute_mysql1 // Run data modification statements
transaction_mysql1 // Manage transactions
schema_mysql1 // Explore database schema
performance_mysql1 // Analyze query performanceClean Architecture
The server follows Clean Architecture principles with these layers:
- Domain Layer: Core business entities and interfaces
- Repository Layer: Data access implementations
- Use Case Layer: Application business logic
- Delivery Layer: External interfaces (MCP tools)
Features
- Simultaneous Multi-Database Support: Connect to multiple MySQL, PostgreSQL, SQLite, and Oracle databases concurrently
- Lazy Loading Mode: Defer connection establishment until first use - perfect for setups with 10+ databases (enable with
--lazy-loadingflag) - Database-Specific Tool Generation: Auto-creates specialized tools for each connected database
- Clean Architecture: Modular design with clear separation of concerns
- OpenAI Agents SDK Compatibility: Full compatibility for seamless AI assistant integration
- Dynamic Database Tools: Execute queries, run statements, manage transactions, explore schemas, analyze performance
- Unified Interface: Consistent interaction patterns across different database types
- Connection Management: Simple configuration for multiple database connections
- Health Check: Automatic validation of database connectivity on startup
Supported Databases
| Database | Status | Features |
|---|---|---|
| MySQL | ✅ Full Support | Queries, Transactions, Schema Analysis, Performance Insights |
| PostgreSQL | ✅ Full Support (v9.6-17) | Queries, Transactions, Schema Analysis, Performance Insights |
| SQLite | ✅ Full Support | File-based & In-memory databases, SQLCipher encryption support |
| Oracle | ✅ Full Support (10g-23c) | Queries, Transactions, Schema Analysis, RAC, Cloud Wallet, TNS |
| TimescaleDB | ✅ Full Support | Hypertables, Time-Series Queries, Continuous Aggregates, Compression, Retention Policies |
Deployment Options
The DB MCP Server can be deployed in multiple ways to suit different environments and integration needs:
Docker Deployment
# Pull the latest image
docker pull freepeak/db-mcp-server:latest
# Run with mounted config file
docker run -p 9092:9092 \
-v $(pwd)/config.json:/app/my-config.json \
-e TRANSPORT_MODE=sse \
-e CONFIG_PATH=/app/my-config.json \
freepeak/db-mcp-serverNote: Mount to
/app/my-config.jsonas the container has a default file at/app/config.json.
STDIO Mode (IDE Integration)
# Run the server in STDIO mode
./bin/server -t stdio -c config.jsonFor Cursor IDE integration, add to .cursor/mcp.json:
{
"mcpServers": {
"stdio-db-mcp-server": {
"command": "/path/to/db-mcp-server/server",
"args": ["-t", "stdio", "-c", "/path/to/config.json"]
}
}
}SSE Mode (Server-Sent Events)
# Default configuration (localhost:9092)
./bin/server -t sse -c config.json
# Custom host and port
./bin/server -t sse -host 0.0.0.0 -port 8080 -c config.jsonClient connection endpoint: http://localhost:9092/sse
Source Code Installation
# Clone the repository
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server
# Build the server
make build
# Run the server
./bin/server -t sse -c config.jsonConfiguration
Database Configuration File
Create a config.json file with your database connections:
{
"connections": [
{
"id": "mysql1",
"type": "mysql",
"host": "mysql1",
"port": 3306,
"name": "db1",
"user": "user1",
"password": "password1",
"query_timeout": 60,
"max_open_conns": 20,
"max_idle_conns": 5,
"conn_max_lifetime_seconds": 300,
"conn_max_idle_time_seconds": 60
},
{
"id": "postgres1",
"type": "postgres",
"host": "postgres1",
"port": 5432,
"name": "db1",
"user": "user1",
"password": "password1"
},
{
"id": "sqlite_app",
"type": "sqlite",
"database_path": "./data/app.db",
"journal_mode": "WAL",
"cache_size": 2000,
"read_only": false,
"use_modernc_driver": true,
"query_timeout": 30,
"max_open_conns": 1,
"max_idle_conns": 1
},
{
"id": "sqlite_encrypted",
"type": "sqlite",
"database_path": "./data/secure.db",
"encryption_key": "your-secret-key-here",
"journal_mode": "WAL",
"use_modernc_driver": false
},
{
"id": "sqlite_memory",
"type": "sqlite",
"database_path": ":memory:",
"cache_size": 1000,
"use_modernc_driver": true
}
]
}Command-Line Options
# Basic syntax
./bin/server -t <transport> -c <config-file>
# SSE transport options
./bin/server -t sse -host <hostname> -port <port> -c <config-file>
# Lazy loading mode (recommended for 10+ databases)
./bin/server -t stdio -c <config-file> --lazy-loading
# Customize log directory (useful for multi-project setups)
./bin/server -t stdio -c <config-file> -log-dir /tmp/db-mcp-logs
# Inline database configuration
./bin/server -t stdio -db-config '{"connections":[...]}'
# Environment variable configuration
export DB_CONFIG='{"connections":[...]}'
./bin/server -t stdioAvailable Flags:
-t, -transport: Transport mode (stdioorsse)-c, -config: Path to database configuration file-p, -port: Server port for SSE mode (default: 9092)-h, -host: Server host for SSE mode (default: localhost)-log-level: Log level (debug,info,warn,error)-log-dir: Directory for log files (default:./logsin current directory)-db-config: Inline JSON database configuration
SQLite Configuration Options
When using SQLite databases, you can leverage these additional configuration options:
SQLite Connection Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
database_path | string | Required | Path to SQLite database file or :memory: for in-memory |
encryption_key | string | - | Key for SQLCipher encrypted databases |
read_only | boolean | false | Open database in read-only mode |
cache_size | integer | 2000 | SQLite cache size in pages |
journal_mode | string | "WAL" | Journal mode: DELETE, TRUNCATE, PERSIST, WAL, OFF |
use_modernc_driver | boolean | true | Use modernc.org/sqlite (CGO-free) or mattn/go-sqlite3 |
SQLite Examples
Basic File Database
{
"id": "my_sqlite_db",
"type": "sqlite",
"database_path": "./data/myapp.db",
"journal_mode": "WAL",
"cache_size": 2000
}Encrypted Database (SQLCipher)
{
"id": "encrypted_db",
"type": "sqlite",
"database_path": "./data/secure.db",
"encryption_key": "your-secret-encryption-key",
"use_modernc_driver": false
}In-Memory Database
{
"id": "memory_db",
"type": "sqlite",
"database_path": ":memory:",
"cache_size": 1000
}Read-Only Database
{
"id": "reference_data",
"type": "sqlite",
"database_path": "./data/reference.db",
"read_only": true,
"journal_mode": "DELETE"
}Oracle Configuration Options
When using Oracle databases, you can leverage these additional configuration options:
Oracle Connection Parameters
| Parameter | Type | Default | Description |
|---|---|---|---|
host | string | Required | Oracle database host |
port | integer | 1521 | Oracle listener port |
service_name | string | - | Service name (recommended for RAC) |
sid | string | - | System identifier (legacy, use service_name instead) |
user | string | Required | Database username |
password | string | Required | Database password |
wallet_location | string | - | Path to Oracle Cloud wallet directory |
tns_admin | string | - | Path to directory containing tnsnames.ora |
tns_entry | string | - | Named entry from tnsnames.ora |
edition | string | - | Edition-Based Redefinition edition name |
pooling | boolean | false | Enable driver-level connection pooling |
standby_sessions | boolean | false | Allow queries on standby databases |
nls_lang | string | AMERICAN_AMERICA.AL32UTF8 | Character set configuration |
Oracle Examples
Basic Oracle Connection (Development)
{
"id": "oracle_dev",
"type": "oracle",
"host": "localhost",
"port": 1521,
"service_name": "XEPDB1",
"user": "testuser",
"password": "testpass",
"max_open_conns": 50,
"max_idle_conns": 10,
"conn_max_lifetime_seconds": 1800
}Oracle with SID (Legacy)
{
"id": "oracle_legacy",
"type": "oracle",
"host": "oracledb.company.com",
"port": 1521,
"sid": "ORCL",
"user": "app_user",
"password": "app_password"
}Oracle Cloud Autonomous Database (with Wallet)
{
"id": "oracle_cloud",
"type": "oracle",
"user": "ADMIN",
"password": "your-cloud-password",
"wallet_location": "/path/to/wallet_DBNAME",
"serv
…