souhardyak/mcp-db-server repository overview

⁠MCP Database Server with Natural Language SQL Queries

An advanced MCP (Model Context Protocol) server that bridges AI agents with relational databases through natural language processing. Transform plain English questions into SQL queries and receive structured results from PostgreSQL and MySQL databases.

⁠🚀 Key Features

• Multi-Database Support: Seamlessly works with PostgreSQL and MySQL
• Natural Language to SQL: Convert plain English queries to SQL using HuggingFace transformers
• RESTful API: Clean FastAPI-based endpoints for database operations
• Safety First: Read-only operations with query validation and result limits
• Docker Ready: Complete containerization with Docker Compose
• Production Ready: Health checks, logging, and comprehensive error handling
• AI Agent Friendly: Designed specifically for AI agent integration
• Security Focused: Input sanitization, SQL injection protection, and safe defaults

⁠📋 API Endpoints

⁠🔧 Quick Start

⁠Option 1: Docker Compose (Recommended)

git clone https://github.com/Souhar-dya/mcp-db-server.git
cd mcp-db-server
docker-compose up --build

⁠Option 2: Docker Hub Image

# Pull the latest image
docker pull souhardyak/mcp-db-server:latest

# Run with your database
docker run -d \
  -p 8000:8000 \
  -e DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname" \
  souhardyak/mcp-db-server:latest

⁠Option 3: Local Development

# Prerequisites: Python 3.11+, PostgreSQL or MySQL
pip install -r requirements.txt

# Set environment variables
export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname"
# or for MySQL:
# export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname"

# Run the server
python -m app.server

⁠🌟 Natural Language Query Examples

# Get all customers
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show all customers"}'

# Count orders by status
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "count orders by status"}'

# Top customers by order value
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "top 5 customers by total order amount"}'

# Recent orders
curl -X POST "http://localhost:8000/mcp/query" \
  -H "Content-Type: application/json" \
  -d '{"nl_query": "show recent orders from last week"}'

⁠🛡️ Security Features

• Read-Only Operations: Only SELECT queries are allowed
• Query Validation: Automatic detection and blocking of dangerous SQL operations
• Result Limiting: Maximum 50 rows per query (configurable)
• Input Sanitization: Protection against SQL injection
• Safe Defaults: Secure configuration out of the box

⁠⚙️ Environment Variables

⁠🗄️ Sample Database

The project includes a sample database with realistic e-commerce data:

• customers: Customer information (10 sample customers)
• orders: Order records (17 sample orders)
• order_items: Individual items within orders
• order_summary: View combining order and customer data

⁠🔗 Links & Resources

• GitHub Repository: https://github.com/Souhar-dya/mcp-db-server⁠
• Documentation: Available at /docs endpoint when running
• Issues & Support: https://github.com/Souhar-dya/mcp-db-server/issues⁠
• Discussions: https://github.com/Souhar-dya/mcp-db-server/discussions⁠

⁠🤝 Contributing

We welcome contributions! Please:

1. Fork the repository
2. Create your feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add some amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

⁠⭐ Support the Project

If this project helped you, please consider:

• Starring the repository on GitHub
• Sharing it with others who might benefit
• Contributing to the codebase
• Reporting issues and suggesting improvements

⁠📊 Latest Updates

v1.1.0 (2025-09-28) - Fixed async processing bugs, improved Claude Desktop integration, enhanced test database setup

v1.0.0 (2025-09-25) - Initial release with full MCP Database Server implementation

Built with FastAPI, SQLAlchemy, and HuggingFace Transformers

Transform your database interactions with the power of natural language processing!