MCP Database Server MCP server

mcp-db-server

An MCP (Model Context Protocol) server that exposes relational databases (PostgreSQL/MySQL) to AI agents with natural language query support. Transform natural language questions into SQL queries and get structured results.

Features

• Multi-Database Support: 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 error handling
• AI Agent Friendly: Designed specifically for AI agent integration

Version 1.4.0 Changes

• Added mandatory X-API-Key authentication for all database HTTP endpoints; /health remains public for health checks.
• Removed unrestricted credentialed CORS and made allowed origins explicitly configurable.
• Changed the default HTTP bind address to 127.0.0.1.
• Added table-name validation against existing database tables to block SQL injection through table routes.
• Added PostgreSQL sslmode=require compatibility for asyncpg connections.
• Updated Docker Compose, environment examples, and documentation for secure API-key configuration.
• Published Docker images:
• souhardyak/mcp-db-server:1.4.0
• souhardyak/mcp-db-server:latest
• Added GitHub Container Registry publishing for:
• ghcr.io/souhar-dya/mcp-db-server:1.4.0
• ghcr.io/souhar-dya/mcp-db-server:latest

API Endpoints

Quick Start

Option 1: Docker Compose (Recommended)

1. Clone and start the services:

git clone https://github.com/Souhar-dya/mcp-db-server.git
   cd mcp-db-server
   export MCP_API_KEY="$(openssl rand -hex 32)"
   docker-compose up --build

1. Test the endpoints:

# Health check
   curl http://localhost:8000/health

   # List tables (requires the configured API key)
   curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/list_tables

   # Describe a table
   curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/describe/customers

   # Natural language query
   curl -X POST "http://localhost:8000/mcp/query" \
     -H "X-API-Key: $MCP_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"nl_query": "show top 5 customers by total orders"}'

Option 2: Local Development

1. Prerequisites:

• Python 3.11+
• PostgreSQL or MySQL database

1. Install dependencies:

pip install -r requirements.txt

1. Set environment variables:

export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname"
   export MCP_API_KEY="$(openssl rand -hex 32)"
   # or for MySQL:
   # export DATABASE_URL="mysql+pymysql://user:password@localhost:3306/dbname"

Shortened. The full README is on GitHub.