Multi Database MCP Server

<h3>A powerful multi-database server implementing the Model Context Protocol (MCP) to provide AI assistants with structured access to databases.</h3>

<div class="toc">
<a href="#overview">Overview</a> •
<a href="#core-concepts">Core Concepts</a> •
<a href="#features">Features</a> •
<a href="#supported-databases">Supported Databases</a> •
<a href="#deployment-options">Deployment Options</a> •
<a href="#configuration">Configuration</a> •
<a href="#available-tools">Available Tools</a> •
<a href="#examples">Examples</a> •
<a href="#troubleshooting">Troubleshooting</a> •
<a href="#contributing">Contributing</a>
</div>

</div>

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 performance

Clean Architecture

The server follows Clean Architecture principles with these layers:

1. Domain Layer: Core business entities and interfaces
2. Repository Layer: Data access implementations
3. Use Case Layer: Application business logic
4. 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-loading flag)
- 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
- Production Guardrails: Per-database read_only enforcement (blocks writes through both query_ and execute_ tools), max_rows result truncation with explicit notices, and per-query timeouts

Production Guardrails

Protect agent sessions against runaway queries and accidental writes:

| Setting | Scope | Effect |
|---------|-------|--------|
| "read_only": true | per database | Blocks write statements (INSERT, UPDATE, DELETE, DDL, data-modifying CTEs, stacked writes) through both query and execute tools, and enforces rejection at the database engine itself on PostgreSQL/TimescaleDB (default_transaction_read_only=on) and MySQL (transaction_read_only=1); SQLite opens mode=ro. Classification strips comments and string literals and defaults to deny for unrecognized statements. |
| "max_rows": 1000 | per database | Truncates result sets at N rows and appends an explicit [Truncated] notice so the model knows to refine its query instead of losing context. 0 (default) means unlimited. |
| "query_timeout": 30 | per database | Cancels queries that exceed the timeout in seconds. |

> Defense in depth: read-only is enforced in three layers — application classifier, engine session defaults, and (recommended) least-privilege database users. Oracle currently relies on the classifier plus user privileges.

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

```bash