Multi Database MCP Server
What is DB MCP Server?
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:
Dynamic Tool Generation
For each connected database, the server automatically generates a set of specialized tools:
Clean 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 and interact with multiple MySQL and PostgreSQL databases concurrently
- 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 with the OpenAI Agents SDK for seamless integration with AI assistants
- Dynamic Database Tools:
- Unified Interface: Consistent interaction patterns across different database types
- Connection Management: Simple configuration for multiple database connections
Currently Supported Databases
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
Quick Start
Using Docker
The quickest way to get started is with Docker:
Note: We mount to/app/my-config.jsonbecause the container already has a file at/app/config.json.
Platform Support
The Docker image supports multiple platforms:
linux/amd64- For Intel/AMD based systems (most Linux/Windows servers and desktops)
linux/arm64- For ARM64 based systems (Apple Silicon Macs, ARM servers)
If you encounter platform mismatch errors (e.g., "The requested image's platform does not match the detected host platform"), specify the platform explicitly:
From Source
Running the Server
The server supports multiple transport modes to fit different use cases:
STDIO Mode (for IDE integration)
Ideal for integration with AI coding assistants:
Output will be sent as JSON-RPC messages to stdout, while logs go to stderr.
For Cursor integration, add this to your
.cursor/mcp.json:SSE Mode (Server-Sent Events)
For web-based applications and services:
Connect your client to
http://localhost:9092/sse for the event stream.Docker Compose
For development environments with database containers, we provide a complete docker-compose.yml file:
Note: Code block was split into 2 parts due to size limits.
Key features of this docker-compose setup:
- The db-mcp-server container waits for all database services to be ready before starting
- Multiple database types and versions are included (MySQL 8.0, PostgreSQL 15, 16.3, and 17)
- All databases include health checks to ensure they're fully initialized before the server connects
- Persistent volumes for all database services
- Exposed ports for direct database access if needed
The setup uses a
wait-for-it.sh script to ensure all database services are fully ready before starting the server. This script checks if a TCP host/port is available before proceeding. You need to include this script in your project directory. The Docker setup mounts this script into the container and uses it to verify database availability.To use this setup:
Make sure your config.json file includes connection details matching the services defined in docker-compose.yml.
Configuration
Database Configuration
Create a
config.json file with your database connections:When using the docker-compose setup, note that the
host values should match the service names in the docker-compose.yml file.Command-Line Options
The server supports various command-line options:
Available Tools
For each connected database (e.g., "mysql1", "mysql2"), the server creates:
Tool Naming Convention
The server automatically generates tools with names following this format:
Where:
<tool_type>: One of: query, execute, transaction, schema, performance
<database_id>: The ID of the database as defined in your configuration
Example tool names for a database with ID "mysql1":
query_mysql1
execute_mysql1
transaction_mysql1
schema_mysql1
performance_mysql1
Database-Specific Tools
query_<dbid>: Execute SQL queries on the specified database
execute_<dbid>: Execute SQL statements (INSERT, UPDATE, DELETE)
transaction_<dbid>: Manage database transactions
schema_<dbid>: Get database schema information
performance_<dbid>: Analyze query performance
Global Tools
list_databases: List all configured database connections
Examples
Querying Multiple Databases
Executing Transactions
Roadmap
We're committed to expanding DB MCP Server to support a wide range of database systems:
Q3 2025
- MongoDB - Support for document-oriented database operations
- SQLite - Lightweight embedded database integration
- MariaDB - Complete feature parity with MySQL implementation
Q4 2025
- Microsoft SQL Server - Enterprise database support with T-SQL capabilities
- Oracle Database - Enterprise-grade integration
- Redis - Key-value store operations
2026
- Cassandra - Distributed NoSQL database support
- Elasticsearch - Specialized search and analytics capabilities
- CockroachDB - Distributed SQL database for global-scale applications
- DynamoDB - AWS-native NoSQL database integration
- Neo4j - Graph database support
- ClickHouse - Analytics database support
Troubleshooting
Common Issues
- Connection Errors: Verify your database connection settings in
config.json
- Tool Not Found: Ensure the server is running and check tool name prefixes
- Failed Queries: Check your SQL syntax and database permissions
- Docker Volume Mount Errors: If you see errors like
mountpoint for /app/config.json: not a directory, it's because the container already has a file at that path. Mount to a different path (e.g.,/app/my-config.json) and update your configuration accordingly.
- Docker Command Errors: If you encounter command-related errors with Docker, use one of these approaches:
- Wait-for-it.sh Missing or Not Working: If you see errors related to wait-for-it.sh:
Logs
The server writes logs to:
- STDIO mode: stderr
- SSE mode: stdout and
./logs/db-mcp-server.log
Enable debug logging with the
-debug flag:Contributing
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch:
git checkout -b new-feature
- Commit your changes:
git commit -am 'Add new feature'
- Push to the branch:
git push origin new-feature
- Submit a pull request
Please ensure your code follows our coding standards and includes appropriate tests.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support & Contact
- For questions or issues, email mnhatlinh.doan@gmail.com
- Open an issue directly: Issue Tracker
- If DB MCP Server helps your work, please consider supporting:
Cursor Integration
Tool Naming Convention
The MCP server registers tools with names that match the format Cursor expects. The tool names follow this format:
For example:
mcp_mysql1_db_mcp_server_stdio_schema_mysql1_dbThe server uses the name
mysql1_db_mcp_server_stdio by default, which should match your Cursor configuration in the mcp.json file.Cursor Configuration
In your Cursor configuration (
~/.cursor/mcp.json), you should have a configuration like:The server will automatically register tools with simple names that match the database identifiers in your configuration.
Using MCP Tools in Cursor
Once your DB MCP Server is running and properly configured in Cursor, you can use the MCP tools in your AI assistant conversations. The tools follow this naming pattern:
Where:
<server_name>is the name defined in your .cursor/mcp.json (e.g., "multidb")
<tool_type>is one of: query, execute, transaction, schema, performance, list_databases
<database_id>is the database ID from your configuration (not needed for list_databases)
Examples:
For a server named "multidb" with a database ID "mysql1":
- Listing all databases:
- Querying the database:
- Viewing database schema:
- Executing statements:
- Managing transactions:
Troubleshooting MCP Tools in Cursor
If the AI assistant can't call the MCP tools:
- Make sure the server is running (check with
ps aux | grep server)
- Verify your .cursor/mcp.json configuration is correct
- Ensure the server_name in .env matches what's in your MCP tool calls
- Restart Cursor after making configuration changes
- Check the logs in the logs/ directory for any errors
OpenAI Agents SDK Integration
The DB MCP Server fully supports OpenAI's Agents SDK, allowing you to create AI agents that can interact with databases directly.
Prerequisites
- OpenAI account with API access
- OpenAI Agents SDK installed:
pip install openai-agents
- A running DB MCP Server instance (SSE mode)
Basic Integration Example
Here's how to integrate the DB MCP Server with an OpenAI Agent:
Testing Your Integration
The repository includes a test script to verify compatibility with the OpenAI Agents SDK:
The script will:
- Build the server with the latest changes
- Start the server if it's not already running
- Test the connection with the OpenAI Agents SDK
- Report if the integration is working correctly
Troubleshooting Agents SDK Integration
If you encounter issues:
- Ensure the server is running in SSE mode on the expected port
- Check that your OpenAI API key is set as an environment variable
- Verify that your agent's instructions mention the database tools specifically
- Inspect the server logs for any error messages
Star History
Multi Database MCP Server
What is DB MCP Server?
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:
Dynamic Tool Generation
For each connected database, the server automatically generates a set of specialized tools:
Clean 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 and interact with multiple MySQL and PostgreSQL databases concurrently
- 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 with the OpenAI Agents SDK for seamless integration with AI assistants
- Dynamic Database Tools:
- Unified Interface: Consistent interaction patterns across different database types
- Connection Management: Simple configuration for multiple database connections
Currently Supported Databases
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
[object Object] | [object Object] | [object Object] |
Quick Start
Using Docker
The quickest way to get started is with Docker:
Note: We mount to/app/my-config.jsonbecause the container already has a file at/app/config.json.
Platform Support
The Docker image supports multiple platforms:
linux/amd64- For Intel/AMD based systems (most Linux/Windows servers and desktops)
linux/arm64- For ARM64 based systems (Apple Silicon Macs, ARM servers)
If you encounter platform mismatch errors (e.g., "The requested image's platform does not match the detected host platform"), specify the platform explicitly:
From Source
Running the Server
The server supports multiple transport modes to fit different use cases:
STDIO Mode (for IDE integration)
Ideal for integration with AI coding assistants:
Output will be sent as JSON-RPC messages to stdout, while logs go to stderr.
For Cursor integration, add this to your
.cursor/mcp.json:SSE Mode (Server-Sent Events)
For web-based applications and services:
Connect your client to
http://localhost:9092/sse for the event stream.Docker Compose
For development environments with database containers, we provide a complete docker-compose.yml file:
Note: Code block was split into 2 parts due to size limits.
Key features of this docker-compose setup:
- The db-mcp-server container waits for all database services to be ready before starting
- Multiple database types and versions are included (MySQL 8.0, PostgreSQL 15, 16.3, and 17)
- All databases include health checks to ensure they're fully initialized before the server connects
- Persistent volumes for all database services
- Exposed ports for direct database access if needed
The setup uses a
wait-for-it.sh script to ensure all database services are fully ready before starting the server. This script checks if a TCP host/port is available before proceeding. You need to include this script in your project directory. The Docker setup mounts this script into the container and uses it to verify database availability.To use this setup:
Make sure your config.json file includes connection details matching the services defined in docker-compose.yml.
Configuration
Database Configuration
Create a
config.json file with your database connections:When using the docker-compose setup, note that the
host values should match the service names in the docker-compose.yml file.Command-Line Options
The server supports various command-line options:
Available Tools
For each connected database (e.g., "mysql1", "mysql2"), the server creates:
Tool Naming Convention
The server automatically generates tools with names following this format:
Where:
<tool_type>: One of: query, execute, transaction, schema, performance
<database_id>: The ID of the database as defined in your configuration
Example tool names for a database with ID "mysql1":
query_mysql1
execute_mysql1
transaction_mysql1
schema_mysql1
performance_mysql1
Database-Specific Tools
query_<dbid>: Execute SQL queries on the specified database
execute_<dbid>: Execute SQL statements (INSERT, UPDATE, DELETE)
transaction_<dbid>: Manage database transactions
schema_<dbid>: Get database schema information
performance_<dbid>: Analyze query performance
Global Tools
list_databases: List all configured database connections
Examples
Querying Multiple Databases
Executing Transactions
Roadmap
We're committed to expanding DB MCP Server to support a wide range of database systems:
Q3 2025
- MongoDB - Support for document-oriented database operations
- SQLite - Lightweight embedded database integration
- MariaDB - Complete feature parity with MySQL implementation
Q4 2025
- Microsoft SQL Server - Enterprise database support with T-SQL capabilities
- Oracle Database - Enterprise-grade integration
- Redis - Key-value store operations
2026
- Cassandra - Distributed NoSQL database support
- Elasticsearch - Specialized search and analytics capabilities
- CockroachDB - Distributed SQL database for global-scale applications
- DynamoDB - AWS-native NoSQL database integration
- Neo4j - Graph database support
- ClickHouse - Analytics database support
Troubleshooting
Common Issues
- Connection Errors: Verify your database connection settings in
config.json
- Tool Not Found: Ensure the server is running and check tool name prefixes
- Failed Queries: Check your SQL syntax and database permissions
- Docker Volume Mount Errors: If you see errors like
mountpoint for /app/config.json: not a directory, it's because the container already has a file at that path. Mount to a different path (e.g.,/app/my-config.json) and update your configuration accordingly.
- Docker Command Errors: If you encounter command-related errors with Docker, use one of these approaches:
- Wait-for-it.sh Missing or Not Working: If you see errors related to wait-for-it.sh:
Logs
The server writes logs to:
- STDIO mode: stderr
- SSE mode: stdout and
./logs/db-mcp-server.log
Enable debug logging with the
-debug flag:Contributing
Contributions are welcome! Here's how you can help:
- Fork the repository
- Create a feature branch:
git checkout -b new-feature
- Commit your changes:
git commit -am 'Add new feature'
- Push to the branch:
git push origin new-feature
- Submit a pull request
Please ensure your code follows our coding standards and includes appropriate tests.
License
This project is licensed under the MIT License - see the LICENSE file for details.
Support & Contact
- For questions or issues, email mnhatlinh.doan@gmail.com
- Open an issue directly: Issue Tracker
- If DB MCP Server helps your work, please consider supporting:
Cursor Integration
Tool Naming Convention
The MCP server registers tools with names that match the format Cursor expects. The tool names follow this format:
For example:
mcp_mysql1_db_mcp_server_stdio_schema_mysql1_dbThe server uses the name
mysql1_db_mcp_server_stdio by default, which should match your Cursor configuration in the mcp.json file.Cursor Configuration
In your Cursor configuration (
~/.cursor/mcp.json), you should have a configuration like:The server will automatically register tools with simple names that match the database identifiers in your configuration.
Using MCP Tools in Cursor
Once your DB MCP Server is running and properly configured in Cursor, you can use the MCP tools in your AI assistant conversations. The tools follow this naming pattern:
Where:
<server_name>is the name defined in your .cursor/mcp.json (e.g., "multidb")
<tool_type>is one of: query, execute, transaction, schema, performance, list_databases
<database_id>is the database ID from your configuration (not needed for list_databases)
Examples:
For a server named "multidb" with a database ID "mysql1":
- Listing all databases:
- Querying the database:
- Viewing database schema:
- Executing statements:
- Managing transactions:
Troubleshooting MCP Tools in Cursor
If the AI assistant can't call the MCP tools:
- Make sure the server is running (check with
ps aux | grep server)
- Verify your .cursor/mcp.json configuration is correct
- Ensure the server_name in .env matches what's in your MCP tool calls
- Restart Cursor after making configuration changes
- Check the logs in the logs/ directory for any errors
OpenAI Agents SDK Integration
The DB MCP Server fully supports OpenAI's Agents SDK, allowing you to create AI agents that can interact with databases directly.
Prerequisites
- OpenAI account with API access
- OpenAI Agents SDK installed:
pip install openai-agents
- A running DB MCP Server instance (SSE mode)
Basic Integration Example
Here's how to integrate the DB MCP Server with an OpenAI Agent:
Testing Your Integration
The repository includes a test script to verify compatibility with the OpenAI Agents SDK:
The script will:
- Build the server with the latest changes
- Start the server if it's not already running
- Test the connection with the OpenAI Agents SDK
- Report if the integration is working correctly
Troubleshooting Agents SDK Integration
If you encounter issues:
- Ensure the server is running in SSE mode on the expected port
- Check that your OpenAI API key is set as an environment variable
- Verify that your agent's instructions mention the database tools specifically
- Inspect the server logs for any error messages