Database MCP Server
A production-ready Model Context Protocol (MCP) provider for SQL databases, built using various vibe coding tools. Supports MySQL, MariaDB, PostgreSQL, and SQLite. Features robust connection pooling, secure AES-GCM credential storage, structured JSON logging, comprehensive schema introspection, and a full suite of 21 MCP tools. Built and tested with Go 1.26.0.
🚀 Quick Start
# Clone the repository
git clone https://github.com/guyinwonder168/database-mcp-server.git
cd database-mcp-server
# Build the server
go build -o mcp-server ./cmd/server/main.go
# Run the server
./mcp-server
📦 Container Package (GHCR)
# Pull the release image
docker pull ghcr.io/guyinwonder168/database-mcp-server:v1.6.3
# Run with stdio transport
docker run --rm -i ghcr.io/guyinwonder168/database-mcp-server:v1.6.3
# Persist config.yaml and logs on host
mkdir -p ./.mcp-data
docker run --rm -i \
-v "$(pwd)/.mcp-data:/app" \
ghcr.io/guyinwonder168/database-mcp-server:v1.6.3
Package registry: https://github.com/guyinwonder168/database-mcp-server/pkgs/container/database-mcp-server
📋 Features
- 🔧 Interactive Setup - Auto-creates
config.yamlif missing; all configuration is managed via MCP actions - 👥 Profile Management - Create, update, delete, or clone database profiles via MCP
- ⚡ SQL Execution - Run arbitrary SQL queries (with read-only enforcement)
- 🔍 Schema Introspection - List tables/views with schema info, describe table schemas, list databases, discover joins, and browse schemas
- 🗂️ Multi-Schema Support - Work with tables in any PostgreSQL schema with automatic detection and schema-qualified queries
- 📊 Sample Data Fetching - Fetch sample rows to infer data formats and value ranges
- 🔗 Automated Join Discovery - Suggest JOIN SQL for building complex queries
- 🚦 Query Optimization - EXPLAIN-based analysis with findings and performance estimates
- 🛡️ Query Validation - Syntax, logic, and security checks before execution
- 🤖 Smart Query Builder - Generate SQL queries programmatically (integrated into analyze-schema AIQuerySuggestions)
- 🔒 Read-only Profiles - Prevent write operations on selected profiles
- 🔐 Secure Credentials - Passwords are encrypted at rest using AES-GCM (256-bit)
- 🏊 Connection Pooling - Efficient, configurable pooling with max pool size
- 📝 Structured Logging & Error Handling - All actions and errors are logged as structured JSON; actionable error responses
- 🛠️ Tool Discovery -
list-toolsMCP action returns a machine-readable list of all available tools/actions - 🔌 Official MCP Protocol - Communication via stdio (not HTTP server; JSON is exchanged over stdio via official Go MCP SDK)
- 📈 Business Intelligence - Discover KPIs, trends, anomalies, and distribution patterns via
discover-insights - 🧭 Data Lineage - Analyze upstream/downstream dependencies via
analyze-data-lineage - 🧱 Schema Evolution Tracking - Track schema snapshots, detect drift, and generate migration scripts via
track-schema-changes - 🧬 Advanced Data Profiling - Optional statistical/pattern profiling for
analyze-schemaviaprofiling: true - 🌐 Multi-Database Federation - Execute federated subqueries with cross-profile joins via
federated-query
🛠️ Supported MCP Tools
🤖 Model Compatibility
- Default schema mode is
compactfor tool-first and strict declaration-budget clients. - Optional
standardmode keeps verbose tool descriptions for human-readable metadata. - All 21 MCP tools are always registered.
- Gemini Compatibility: Schemas are automatically sanitized to comply with Google Gemini's OpenAPI 3.0 subset requirements (single
typevalues, noadditionalProperties: false, properitemsschemas). - Use
get-tool-helpfor per-tool examples and troubleshooting without inflating startup metadata.
config.yaml:
schema_mode: compact # compact|standard
Recommended startup configuration for strict tool-loading clients:
schema_mode: compact
Helper tool request example:
{
"tool_name": "execute-sql",
"topic": "all"
}
📖 Documentation
Core Documentation
- 📋 API Documentation - Detailed API specifications and examples
- 📊 Implementation Status - Current implementation tracking
- 🏗️ Technical Specifications - Architecture and design details
- 📝 PRD Analysis - Product requirements analysis with AI perspective
- 🔍 Schema Introspection Queries - Database-specific queries
- 🧪 Test Enhanced Schema - Test schema documentation
- 🗺️ Enhancement Roadmap - Strategic development planning
Memory Bank Documentation
The project includes a comprehensive memory bank system for AI assistants, located in .kilocode/rules/memory-bank/:
- 🏗️ Architecture - System architecture and component relationships
- 📋 Brief - Project overview and requirements
- 📊 Context - Current state and recent changes
- 🎯 Product - Problem statement and solution overview
- 💻 Tech - Technology stack and development setup
Project Planning
- 🗺️ Roadmap - Consolidated enhancement plan
- 📊 Vertical Slices (History) - Phase-by-phase development breakdown
- 🔍 Architecture Validation (History) - Technical compatibility analysis
- 🐛 MCP Tool Detection Fix (History) - Critical bug fix documentation
Version History
- 📋 CHANGELOG - Detailed release notes and version history
🤝 Contributing
We welcome contributions! Please see our Contributing Guidelines for development setup and workflow.
📄 License
This project is licensed under the MIT License.
🔐 Security
For security policies and vulnerability reporting, please see our Security Policy.
📜 Code of Conduct
Please read our Code of Conduct for community guidelines.
🧪 Testing
# Run all tests
go test ./...
# Run tests with coverage
go test -cover ./...
# Run specific test suites
go test ./internal/mcp -run "TestDescribe" -v # MySQL/PostgreSQL descriptor tests
go test ./internal/mcp -run "TestLoadLineage" -v # Lineage edge tests
Testing Strategy
- MySQL/PostgreSQL: Uses go-sqlmock for database-specific query testing without requiring real database connections
- SQLite: Uses real in-memory databases for actual SQLite functionality testing
- Live Integration: Optional live database tests via
DB_MCP_IT_*environment variables
📊 Project Status
-
Version: v1.6.3
-
Built with: Various vibe coding tools
-
Status: Production Ready ✅
-
All 21 MCP tools are fully implemented and OpenAPI-aligned.
-
Enhanced schema introspection and sample data features.
-
Optional advanced profiling in
analyze-schemafor column-level statistics, pattern detection, and quality scoring. -
AES-GCM encryption, connection pooling, and structured error handling are enforced.
-
Comprehensive unit and integration tests included.
-
Ready for production use.
-
Business Intelligence Discovery: Added
discover-insightstool for automatic KPI, trend, anomaly, and distribution analysis
Enhancement Planning
Current Development Status: The Database MCP Server is production-ready with a comprehensive enhancement roadmap in progress.
Implementation Phases:
- Phase 1 (Completed): Query optimization, validation, and enhanced NLP
- Phase 2 (Completed): Data lineage and business intelligence
- Phase 3 (Completed): Schema evolution, advanced profiling, and multi-database federation
- Phase 4 (Planned): Cross-database data migration with async jobs, schema translation, and resume capability
Current Progress:
track-schema-changesis implemented with snapshot tracking, history, migration generation, and drift detection.- Advanced profiling for
analyze-schemais implemented with optionalprofilingparameter and backward-compatible response shape. federated-queryis implemented with parser/planner/join/executor/handler modules and dedicated test coverage.configure-profileenhanced withdeleteandcloneactions (v1.3.0).
Planning Documents:
- Enhancement Roadmap - Strategic overview
- Data Migration Design - Phase 4 implementation plan
- Project Plan (History) - Comprehensive implementation strategy
- Vertical Slices (History) - Detailed phase breakdowns
🔍 Multi-Schema Support (PostgreSQL)
This server provides comprehensive multi-schema support for PostgreSQL databases:
Schema-Aware Tools
Connection Pooling Note
This server uses connection pooling per database profile. Due to this architecture:
set-search-pathis intentionally NOT implemented - Session-levelsearch_pathchanges would contaminate other clients using the same pooled connection- Use explicit schema qualification via the
schemaparameter on relevant tools - Auto-detection falls back gracefully:
current_schema()→ first accessible schema →'public'
Example Usage
// Describe table in specific schema
{
"profile_name": "mydb",
"database_name": "mydb",
"table_name": "users",
"schema": "bitnami_redmine"
}
// List all schemas
{
"profile_name": "mydb",
"database_name": "mydb"
}
Ready for immediate enhancement development while maintaining production stability.