The DB MCP Server provides a standardized way for AI models to interact with multiple databases simultaneously.
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.
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"
}
]
}
For each connected database, the server automatically generates a set of 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
The server follows Clean Architecture principles with these layers:
| Database | Status | Features |
|---|---|---|
| MySQL | ✅ Full Support | Queries, Transactions, Schema Analysis, Performance Insights |
| PostgreSQL | ✅ Full Support | Queries, Transactions, Schema Analysis, Performance Insights |
The quickest way to get started is with Docker:
# Pull the latest image
docker pull freepeak/db-mcp-server:latest
# Run with your config mounted
docker run -p 9092:9092 -v $(pwd)/config.json:/app/config.json freepeak/db-mcp-server -t sse -c /app/config.json
# 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 in SSE mode
./server -t sse -c config.json
The server supports multiple transport modes to fit different use cases:
Ideal for integration with AI coding assistants:
# Run the server in STDIO mode
./server -t stdio -c config.json
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:
{
"mcpServers": {
"stdio-db-mcp-server": {
"command": "/path/to/db-mcp-server/server",
"args": [
"-t", "stdio",
"-c", "/path/to/config.json"
]
}
}
}
For web-based applications and services:
# Run with default host (localhost) and port (9092)
./server -t sse -c config.json
# Specify a custom host and port
./server -t sse -host 0.0.0.0 -port 8080 -c config.json
Connect your client to http://localhost:9092/sse for the event stream.
For development environments with database containers:
# docker-compose.yml
version: '3'
services:
db-mcp-server:
image: freepeak/db-mcp-server:latest
ports:
- "9092:9092"
volumes:
- ./config.json:/app/config.json
command: ["-t", "sse", "-c", "/app/config.json"]
depends_on:
- mysql
- postgres
mysql:
image: mysql:8
environment:
MYSQL_ROOT_PASSWORD: rootpassword
MYSQL_DATABASE: testdb
MYSQL_USER: user
MYSQL_PASSWORD: password
ports:
- "3306:3306"
postgres:
image: postgres:14
environment:
POSTGRES_DB: testdb
POSTGRES_USER: user
POSTGRES_PASSWORD: password
ports:
- "5432:5432"
Create a config.json file with your database connections:
{
"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"
}
]
}
The server supports various command-line options:
# Basic options
./server -t <transport> -c <config-file>
# Available transports: stdio, sse
# For SSE transport, additional options:
./server -t sse -host <hostname> -port <port> -c <config-file>
# Direct database configuration:
./server -t stdio -db-config '{"connections":[...]}'
# Environment variable configuration:
export DB_CONFIG='{"connections":[...]}'
./server -t stdio
For each connected database (e.g., "mysql1", "mysql2"), the server creates:
query_<dbid>: Execute SQL queries on the specified database
{
"query": "SELECT * FROM users WHERE age > ?",
"params": [30]
}
execute_<dbid>: Execute SQL statements (INSERT, UPDATE, DELETE)
{
"statement": "INSERT INTO users (name, email) VALUES (?, ?)",
"params": ["John Doe", "[email protected]"]
}
transaction_<dbid>: Manage database transactions
// Begin transaction
{
"action": "begin",
"readOnly": false
}
// Execute within transaction
{
"action": "execute",
"transactionId": "<from begin response>",
"statement": "UPDATE users SET active = ? WHERE id = ?",
"params": [true, 42]
}
// Commit transaction
{
"action": "commit",
"transactionId": "<from begin response>"
}
schema_<dbid>: Get database schema information
{
"random_string": "dummy"
}
performance_<dbid>: Analyze query performance
{
"action": "analyzeQuery",
"query": "SELECT * FROM users WHERE name LIKE ?"
}
list_databases: List all configured database connections
{}
// Query the first database
{
"name": "query_mysql1",
"parameters": {
"query": "SELECT * FROM users LIMIT 5"
}
}
// Query the second database
{
"name": "query_mysql2",
"parameters": {
"query": "SELECT * FROM products LIMIT 5"
}
}
// Begin transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "begin"
}
}
// Response contains transactionId
// Execute within transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "execute",
"transactionId": "tx_12345",
"statement": "INSERT INTO orders (user_id, product_id) VALUES (?, ?)",
"params": [1, 2]
}
}
// Commit transaction
{
"name": "transaction_mysql1",
"parameters": {
"action": "commit",
"transactionId": "tx_12345"
}
}
We're committed to expanding DB MCP Server to support a wide range of database systems:
config.jsonThe server writes logs to:
./logs/db-mcp-server.logEnable debug logging with the -debug flag:
./server -t sse -debug -c config.json
Contributions are welcome! Here's how you can help:
git checkout -b new-featuregit commit -am 'Add new feature'git push origin new-featurePlease ensure your code follows our coding standards and includes appropriate tests.
This project is licensed under the MIT License - see the LICENSE file for details.
