Multi DB MCP Server

<h3>A robust multi-database implementation of the Database Model Context Protocol (DB MCP)</h3>

Features • AI Benefits • Installation • Usage • Documentation • Contributing • License

</div>

📋 Overview

The DB MCP Server is a high-performance implementation of the Database Model Context Protocol designed to revolutionize how AI agents interact with databases. By creating a standardized communication layer between AI models and database systems, it enables AI agents to discover, understand, and manipulate database structures with unprecedented context awareness. Currently supporting MySQL and PostgreSQL databases, with plans to expand to most widely used databases including NoSQL solutions, DB MCP Server eliminates the knowledge gap between AI agents and your data, enabling more intelligent, context-aware database operations that previously required human expertise.

✨ Key Features

AI-Optimized Context Protocol: Provides rich database context to AI agents, enabling them to reason about schema, relationships, and data patterns
Semantic Understanding Bridge: Translates between natural language queries and database operations with full schema awareness
Contextual Database Operations: Allows AI agents to execute database operations with full understanding of schema, constraints, and relationships
Multi-Database Support: Currently supports MySQL and PostgreSQL with plans for expansion
Dynamic Tool Registry: Register, discover, and invoke database tools at runtime via standard protocol AI agents can understand
Editor Integration: First-class support for VS Code and Cursor extensions with AI-aware features
Schema-Aware Assistance: Provides AI models with complete database structure knowledge for better suggestions
Performance Insights: Delivers performance analytics that AI can leverage for optimization recommendations

🧠 AI Integration Benefits

The DB MCP Server transforms how AI agents interact with databases in several key ways:

Enhanced Contextual Understanding

Schema Awareness: AI agents gain complete knowledge of database tables, columns, relationships, and constraints
Semantic Relationship Mapping: Enables AI to understand not just structure but meaning and purpose of data elements
Query Context Preservation: Maintains context between related operations for coherent multi-step reasoning

Intelligent Database Operations

Natural Language to SQL: Translates user intent into optimized database operations with full schema awareness
Context-Aware Query Generation: Creates queries that respect database structure, types, and relationships
Error Prevention: Understands database constraints before execution, preventing common errors
Optimization Suggestions: Provides AI with execution metrics for intelligent query improvement recommendations

Workflow Optimization

Reduced Context Window Usage: Efficiently provides database structure without consuming AI token context
Operation Chaining: Enables complex multi-step operations with persistent context
Intelligent Defaults: Suggests appropriate actions based on database structure and common patterns
Progressive Disclosure: Reveals database complexity progressively as needed by the AI agent

🚀 Installation

Prerequisites

Go 1.18 or later
Supported databases:
- MySQL
- PostgreSQL
- (Additional databases in roadmap)
Docker (optional, for containerized deployment)

Quick Start

# Clone the repository
git clone https://github.com/FreePeak/db-mcp-server.git
cd db-mcp-server

# Copy and configure environment variables
cp .env.example .env
# Edit .env with your configuration

# Option 1: Build and run locally
make build
./mcp-server

# Option 2: Using Docker
docker build -t db-mcp-server .
docker run -p 9090:9090 db-mcp-server

# Option 3: Using Docker Compose (with MySQL)
docker-compose up -d

Docker

# Build the Docker image
docker build -t db-mcp-server .

# Run the container
docker run -p 9090:9090 db-mcp-server

# Run with custom configuration
docker run -p 8080:8080 \
  -e SERVER_PORT=8080 \
  -e LOG_LEVEL=debug \
  -e DB_TYPE=mysql \
  -e DB_HOST=my-database-server \
  db-mcp-server
  
# Run with Docker Compose (includes MySQL database)
docker-compose up -d

🔧 Configuration

DB MCP Server can be configured via environment variables or a .env file:

| Variable | Description | Default | |----------|-------------|---------| | SERVER_PORT | Server port | 9092 | | TRANSPORT_MODE | Transport mode (stdio, sse) | stdio | | LOG_LEVEL | Logging level (debug, info, warn, error) | debug | | DB_TYPE | Database type (mysql, postgres) | mysql | | DB_HOST | Database host | localhost | | DB_PORT | Database port | 3306 | | DB_USER | Database username | iamrevisto | | DB_PASSWORD | Database password | password | | DB_NAME | Database name | revisto | | DB_ROOT_PASSWORD | Database root password (for container setup) | root_password |

See .env.example for more configuration options.

📖 Usage

Integrating with Cursor Edit and AI Agents

DB MCP Server creates a powerful bridge between your databases and AI assistants in Cursor Edit, enabling AI-driven database operations with full context awareness. Configure your Cursor settings in .cursor/mcp.json:

{
    "mcpServers": {
        "db-mcp-server": {
            "url": "http://localhost:9090/sse"
        }
    }
}

To leverage AI-powered database operations:

Configure and start the DB MCP Server using one of the installation methods above
Add the configuration to your Cursor settings
Open Cursor and navigate to a SQL or code file
The AI assistant now has access to your database schema, relationships, and capabilities
Ask the AI to generate, explain, or optimize database queries with full schema awareness
Execute AI-generated queries directly from Cursor

The MCP Server enhances AI assistant capabilities with:

Complete database schema understanding
Relationship-aware query generation
Intelligent query optimization recommendations
Error prevention through constraint awareness
Performance metrics for better suggestions
Context persistence across multiple operations

Example AI Interactions

# Ask the AI for schema information
"What tables are in the database and how are they related?"

# Request query generation with context
"Create a query to find all orders from customers in California with items over $100"

# Get optimization suggestions
"How can I optimize this query that's taking too long to execute?"

# Request complex data operations
"Help me create a transaction that updates inventory levels when an order is placed"

Custom Tool Registration (Server-side)

// Go example
package main

import (
	"context"
	"db-mcpserver/internal/mcp"
)

func main() {
	// Create a custom database tool that AI agents can discover and use
	queryTool := &mcp.Tool{
		Name:        "dbQuery",
		Description: "Executes read-only SQL queries with parameterized inputs",
		InputSchema: mcp.ToolInputSchema{
			Type: "object",
			Properties: map[string]interface{}{
				"query": {
					"type":        "string",
					"description": "SQL query to execute",
				},
				"params": {
					"type":        "array",
					"description": "Query parameters",
					"items": map[string]interface{}{
						"type": "any",
					},
				},
				"timeout": {
					"type":        "integer",
					"description": "Query timeout in milliseconds (optional)",
				},
			},
			Required: []string{"query"},
		},
		Handler: func(ctx context.Context, params map[string]interface{}) (interface{}, error) {
			// Implementation...
			return result, nil
		},
	}

	// Register the tool
	toolRegistry.RegisterTool(queryTool)
}

📚 Documentation

DB MCP Protocol for AI Integration

The server implements the DB MCP protocol with methods specifically designed to enhance AI agent capabilities:

initialize: Sets up the session, transmits schema context, and returns server capabilities
tools/list: Enables AI agents to discover available database tools dynamically
tools/call: Allows AI to execute database tools with full context
editor/context: Updates the server with editor context for better AI awareness
schema/explore: Provides AI with detailed database structure information
cancel: Cancels an in-progress operation

For full protocol documentation, visit the MCP Specification and our database-specific extensions for AI integration.

Tool System

The DB MCP Server includes a powerful AI-aware tool system that provides large language models and AI assistants with a structured way to discover and invoke database tools. Each tool has:

A unique name discoverable by AI
A comprehensive description that AI can understand
A JSON Schema for input validation and AI parameter generation
A structured output format that AI can parse and reason about
A handler function that executes the tool's logic with context awareness

This structure enables AI agents to intelligently select, parameterize, and invoke the right database operations without requiring hard-coded knowledge of your specific database schema.

Built-in Tools for AI Integration

The server includes AI-optimized database tools that provide rich context and capabilities:

| Tool | Description | AI Benefits | |------|-------------|------------| | dbQuery | Executes read-only SQL queries with parameterized inputs | Enables AI to retrieve data with full schema knowledge | | dbExecute | Performs data modification operations (INSERT, UPDATE, DELETE) | Allows AI to safely modify data with constraint awareness | | dbTransaction | Manages SQL transactions with commit and rollback support | Supports AI in creating complex multi-step operations | | dbSchema | Auto-discovers database structure and relationships | Provides AI with complete schema context for reasoning | | dbQueryBuilder | Visual SQL query construction with syntax validation | Helps AI create syntactically correct queries | | dbPerformanceAnalyzer | Identifies slow queries and provides optimization suggestions | Enables AI to suggest performance improvements |

Database Schema Explorer Tool

The MCP Server includes an AI-aware Database Schema Explorer tool (dbSchema) that provides AI models with complete database structural knowledge:

// Get all tables in the database - enables AI to understand available data entities
{
  "name": "dbSchema",
  "arguments": {
    "component": "tables"
  }
}

// Get columns for a specific table - gives AI detailed field information
{
  "name": "dbSchema",
  "arguments": {
    "component": "columns",
    "table": "users"
  }
}

// Get relationships for a specific table or all relationships - helps AI understand data connections
{
  "name": "dbSchema",
  "arguments": {
    "component": "relationships",
    "table": "orders"
  }
}

// Get the full database schema - provides AI with comprehensive structural context
{
  "name": "dbSchema",
  "arguments": {
    "component": "full"
  }
}

The Schema Explorer supports both MySQL and PostgreSQL databases, automatically adapting to your configured database type and providing AI with the appropriate contextual information.

Visual Query Builder Tool

The MCP Server includes a powerful Visual Query Builder tool (dbQueryBuilder) that helps you construct SQL queries with syntax validation:

// Validate a SQL query for syntax errors
{
  "name": "dbQueryBuilder",
  "arguments": {
    "action": "validate",
    "query": "SELECT * FROM users WHERE status = 'active'"
  }
}

// Build a SQL query from components
{
  "name": "dbQueryBuilder",
  "arguments": {
    "action": "build",
    "components": {
      "select": ["id", "name", "email"],
      "from": "users",
      "where": [
        {
          "column": "status",
          "operator": "=",
          "value": "active"
        }
      ],
      "orderBy": [
        {
          "column": "name",
          "direction": "ASC"
        }
      ],
      "limit": 10
    }
  }
}

// Analyze a SQL query for potential issues and performance
{
  "name": "dbQueryBuilder",
  "arguments": {
    "action": "analyze",
    "query": "SELECT u.*, o.* FROM users u JOIN orders o ON u.id = o.user_id WHERE u.status = 'active' AND o.created_at > '2023-01-01'"
  }
}

Example response from a query build operation:

{
  "query": "SELECT id, name, email FROM users WHERE status = 'active' ORDER BY name ASC LIMIT 10",
  "components": {
    "select": ["id", "name", "email"],
    "from": "users",
    "where": [{
      "column": "status",
      "operator": "=",
      "value": "active"
    }],
    "orderBy": [{
      "column": "name",
      "direction": "ASC"
    }],
    "limit": 10
  },
  "validation": {
    "valid": true,
    "query": "SELECT id, name, email FROM users WHERE status = 'active' ORDER BY name ASC LIMIT 10"
  }
}

The Query Builder supports:

SELECT statements with multiple columns
JOIN operations (inner, left, right, full)
WHERE conditions with various operators
GROUP BY and HAVING clauses
ORDER BY with sorting direction
LIMIT and OFFSET for pagination
Syntax validation and error suggestions
Query complexity analysis

Performance Analyzer Tool

The MCP Server includes a powerful Performance Analyzer tool (dbPerformanceAnalyzer) that identifies slow queries and provides optimization suggestions:

// Get slow queries that exceed the configured threshold
{
  "name": "dbPerformanceAnalyzer",
  "arguments": {
    "action": "getSlowQueries",
    "limit": 5
  }
}

// Get metrics for all tracked queries sorted by average duration
{
  "name": "dbPerformanceAnalyzer",
  "arguments": {
    "action": "getMetrics",
    "limit": 10
  }
}

// Analyze a specific query for optimization opportunities
{
  "name": "dbPerformanceAnalyzer",
  "arguments": {
    "action": "analyzeQuery",
    "query": "SELECT * FROM orders JOIN users ON orders.user_id = users.id WHERE orders.status = 'pending'"
  }
}

// Reset all collected performance metrics
{
  "name": "dbPerformanceAnalyzer",
  "arguments": {
    "action": "reset"
  }
}

// Set the threshold for identifying slow queries (in milliseconds)
{
  "name": "dbPerformanceAnalyzer",
  "arguments": {
    "action": "setThreshold",
    "threshold": 300
  }
}

Example response from a performance analysis:

{
  "query": "SELECT * FROM orders JOIN users ON orders.user_id = users.id WHERE orders.status = 'pending'",
  "suggestions": [
    "Avoid using SELECT * - specify only the columns you need",
    "Verify that ORDER BY columns are properly indexed",
    "Consider adding appropriate indexes for frequently queried columns"
  ]
}

Example response from getting slow queries:

{
  "metrics": [
    {
      "query": "SELECT * FROM large_table WHERE status = ?",
      "count": 15,
      "totalDuration": "2.5s",
      "minDuration": "120ms",
      "maxDuration": "750ms",
      "avgDuration": "166ms",
      "lastExecuted": "2025-06-15T14:23:45Z"
    },
    {
      "query": "SELECT order_id, SUM(amount) FROM order_items GROUP BY order_id",
      "count": 8,
      "totalDuration": "1.2s",
      "minDuration": "110ms",
      "maxDuration": "580ms",
      "avgDuration": "150ms",
      "lastExecuted": "2025-06-15T14:20:12Z"
    }
  ],
  "count": 2,
  "threshold": "100ms"
}

The Performance Analyzer automatically tracks all query executions and provides:

Identification of slow-performing queries
Query execution metrics (count, min, max, average durations)
Pattern-based query analysis
Optimization suggestions
Performance trend monitoring
Configurable slow query thresholds

Editor Integration

The server includes support for editor-specific features through the editor/context method, enabling tools to be aware of:

Current SQL file
Selected query
Cursor position
Open database connections
Database structure

🗺️ Roadmap

We're committed to expanding DB MCP Server's AI integration capabilities. Here's our planned development roadmap:

Q2 2025

✅ AI-Aware Schema Explorer - Auto-discover database structure and relationships for AI context
✅ Context-Aware Query Builder - AI-driven SQL query construction with syntax validation
✅ Performance Analyzer with AI Insights - Identify optimization opportunities with AI recommendations

Q3 2025

AI-Powered Data Visualization - Create charts and graphs from query results with AI suggestions
AI-Driven Model Generator - Auto-generate code models from database tables using AI patterns
Multi-DB Support Expansion with Cross-DB AI Reasoning - Add support with AI that understands:
- MongoDB - Document-oriented schema for AI reasoning
- Redis - Key-value pattern recognition for AI
- SQLite - Lightweight database understanding

Q4 2025

AI-Assisted Migration Manager - Version-controlled schema changes with AI recommendations
Intelligent Access Control - AI-aware permissions for database operations
Context-Enriched Query History - Track queries with execution metrics for AI learning
Additional Database Integrations with AI Context:
- Cassandra - Distributed schema understanding
- Elasticsearch - Search-optimized AI interactions
- DynamoDB - NoSQL reasoning capabilities
- Oracle - Enterprise schema comprehension

Future Vision

Complete Database Coverage with Unified AI Context - Support for all major databases with consistent AI interface
AI-Assisted Query Optimization - Smart recommendations using machine learning
Cross-Database AI Operations - Unified interface for heterogeneous database environments
Real-Time Collaborative AI - Multi-user AI assistance for collaborative database work
AI-Powered Plugin System - Community-driven extension marketplace with AI discovery

🤝 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 make sure 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: