Multi Database MCP Server

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

Overview • Core Concepts • Features • Supported Databases • Deployment Options • Configuration • Available Tools • Examples • Troubleshooting • Contributing

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:

| DB_MCP_AUDIT_LOG=/path/audit.jsonl | process | Appends one JSONL record per executed statement — timestamp, op (query/execute/tx_*), database, statement (capped at 10k chars), duration, error. Includes rejected attempts against read-only databases. Best-effort writes never fail a query; file is created with 0600. |

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

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 \
  -e DB_MCP_API_KEY=replace-me-with-a-long-random-string \
  freepeak/db-mcp-server

Note: Mount to /app/my-config.json as the container has a default file at /app/config.json.

API-Key Authentication

The SSE and streamable-HTTP transports accept an Authorization: Bearer <key> header. Set DB_MCP_API_KEY (or pass -api-key) when launching the Docker container; clients must then send the matching bearer token on every request:

curl -H "Authorization: Bearer replace-me-with-a-long-random-string" \
     http://localhost:9092/sse

When no API key is configured the transport remains open (single-user / development use). The middleware lives in internal/delivery/mcp.APIKeyAuth and is exported so you can compose it with your own reverse proxy if you front the container with nginx, Caddy, or Traefik.

STDIO Mode (IDE Integration)

# Run the server in STDIO mode
./bin/server -t stdio -c config.json

For 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.json

Client 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.json

Configuration

Database Configuration File

Create a config.json file with your database connections: