db-mcp-server

<div align="center"> <img src="assets/logo.svg" alt="DB MCP Server Logo" width="300" /> # Multi Database MCP Server [](https://opensource.org/licenses/MIT) [](https://goreportcard.com/report/github.com/FreePeak/db-mcp-server) [](https://pkg.go.dev/github.com/FreePeak/db-mcp-server) [](https://github.com/FreePeak/db-mcp-server/graphs/contributors) <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](https://github.com/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: ```json { "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" } ] } ``` ### Dynamic Tool Generation For each connected database, the server automatically generates specialized tools: ```go // 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 and PostgreSQL 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 ## 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 | | 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 # 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-server ``` > **Note**: Mount to `/app/my-config.json` as the container has a default file at `/app/con