guyinwonder168/database-mcp-server

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 19 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.3.0

# Run with stdio transport
docker run --rm -i ghcr.io/guyinwonder168/database-mcp-server:v1.3.0

# 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.3.0

Package registry: https://github.com/guyinwonder168/database-mcp-server/pkgs/container/database-mcp-server

📋 Features

• 🔧 Interactive Setup - Auto-creates config.yaml if 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, describe table schemas, list databases, and discover joins
• 📊 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-tools MCP 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-schema via profiling: true
• 🌐 Multi-Database Federation - Execute federated subqueries with cross-profile joins via federated-query

🛠️ Supported MCP Tools

🤖 Model Compatibility

• Default schema mode is compact for tool-first and strict declaration-budget clients.
• Optional standard mode keeps verbose tool descriptions for human-readable metadata.
• All 19 MCP tools are always registered.
• Gemini Compatibility: Schemas are automatically sanitized to comply with Google Gemini's OpenAPI 3.0 subset requirements (single type values, no additionalProperties: false, proper items schemas).
• Use get-tool-help for 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

• 📋 - Detailed API specifications and examples
• 📊 - Current implementation tracking
• 🏗️ - Architecture and design details
• 📝 - Product requirements analysis with AI perspective
• 🔍 - Database-specific queries
• 🧪 - Test schema documentation
• 🗺️ - Strategic development planning

Memory Bank Documentation

The project includes a comprehensive memory bank system for AI assistants, located in .kilocode/rules/memory-bank/:

• 🏗️ - System architecture and component relationships
• 📋 - Project overview and requirements
• 📊 - Current state and recent changes
• 🎯 - Problem statement and solution overview
• 💻 - Technology stack and development setup

Project Planning

• 🗺️ - Consolidated enhancement plan
• 📊 - Phase-by-phase development breakdown
• 🔍 - Technical compatibility analysis
• 🐛 - Critical bug fix documentation

Version History

• 📋 - Detailed release notes and version history

🤝 Contributing

We welcome contributions! Please see our for development setup and workflow.

📄 License

This project is licensed under the .

🔐 Security

For security policies and vulnerability reporting, please see our .

📜 Code of Conduct

Please read our for community guidelines.

🧪 Testing

go test ./...

📊 Project Status

• Version: v1.3.0

• Built with: Various vibe coding tools

• Status: Production Ready ✅

• All 19 MCP tools are fully implemented and OpenAPI-aligned.

• Enhanced schema introspection and sample data features.

• Optional advanced profiling in analyze-schema for 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-insights tool 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-changes is implemented with snapshot tracking, history, migration generation, and drift detection.
• Advanced profiling for analyze-schema is implemented with optional profiling parameter and backward-compatible response shape.
• federated-query is implemented with parser/planner/join/executor/handler modules and dedicated test coverage.
• configure-profile enhanced with delete and clone actions (v1.3.0).

Planning Documents:

• - Strategic overview
• - Phase 4 implementation plan
• - Comprehensive implementation strategy
• - Detailed phase breakdowns

Ready for immediate enhancement development while maintaining production stability.