MCP Database 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"

1. Run the server:

   python -m app.server

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

Natural Language Query Examples

The server can understand various types of natural language queries:

# 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"}'

Configuration

Environment Variables

Database Connection Examples

# PostgreSQL

DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb

MySQL

DATABASE_URL=mysql+pymysql://user:pass@localhost:3306/mydb

PostgreSQL with SSL

DATABASE_URL=postgresql+asyncpg://user:pass@localhost:5432/mydb?sslmode=require

Database Connection Examples

# PostgreSQL (local or cloud)

DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname

MySQL (local or cloud)

DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname

PostgreSQL with SSL (cloud, e.g. Neon, Supabase, Aiven)

DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname?sslmode=require

MySQL with SSL (cloud, e.g. Aiven, PlanetScale)

DATABASE_URL=mysql+aiomysql://user:password@host:3306/dbname?ssl-mode=REQUIRED

Note:

- For MySQL cloud providers, the ssl-mode parameter in the URL is ignored by the driver, but SSL is always enabled in the MCP server for cloud connections.

- For PostgreSQL, use sslmode=require for cloud DBs. For MySQL, just use the standard URL; SSL is handled automatically.

- If you see errors about ssl-mode or sslmode, check your URL and ensure you are using the correct driver prefix (mysql+aiomysql or postgresql+asyncpg).

Cloud Database Examples

# Neon (PostgreSQL)

DATABASE_URL=postgresql+asyncpg://username:password@ep-xxxxxx-pooler.us-east-2.aws.neon.tech/dbname

Aiven (MySQL)

DATABASE_URL=mysql+aiomysql://avnadmin:yourpassword@mysql-xxxxxx-username-xxxx.aivencloud.com:11079/defaultdb?ssl-mode=REQUIRED

Docker Usage with Cloud DB

docker run -d \

-p 8000:8000 \ -e DATABASE_URL=" " \ -e MCP_API_KEY=" " \ souhardyak/mcp-db-server:latest

GitHub Container Registry is also available:

docker login ghcr.io

docker pull ghcr.io/souhar-dya/mcp-db-server:latest docker run -d \ -p 8000:8000 \ -e DATABASE_URL=" " \ -e MCP_API_KEY="$MCP_API_KEY" \ ghcr.io/souhar-dya/mcp-db-server:latest

Images are published automatically when a v*.*.* tag is pushed. The workflow also creates the matching GitHub Release. To publish an existing tag such as v1.4.0, open the workflow's Run workflow action and enter 1.4.0. Set the GHCR package visibility to Public in the repository's Packages settings if unauthenticated pulls should be allowed.

Troubleshooting

• If you get connect() got an unexpected keyword argument 'ssl-mode', ignore it: SSL is still enabled.
• For network errors, check firewall and DB credentials.
• For MySQL, always use mysql+aiomysql in the URL for async support.

PostgreSQL SSL connection note

For PostgreSQL cloud providers, use an asyncpg URL and sslmode=require:

DATABASE_URL=postgresql+asyncpg://user:password@host:5432/dbname?sslmode=require

The server normalizes sslmode=require to the ssl option expected by asyncpg. A temporary PostgreSQL verification was completed successfully against a compatible cloud database using CREATE, INSERT, SELECT, UPDATE, DELETE, and DROP; no test data was retained. Never commit or share a connection URL containing a real password.

API key authentication

MCP_API_KEY is a secret that you generate and provide to the server. It protects all database HTTP endpoints through the X-API-Key request header. The /health endpoint remains public for container health checks.

Generate a strong key on Linux or macOS:

export MCP_API_KEY="$(openssl rand -hex 32)"

Generate one in Windows PowerShell:

$bytes = New-Object byte[] 32

$env:MCP_API_KEY = ([BitConverter]::ToString($bytes) -replace "-", "").ToLower()

Start the Docker image with the key:

docker run -d \

-p 8000:8000 \ -e DATABASE_URL=" " \ -e MCP_API_KEY="$MCP_API_KEY" \ souhardyak/mcp-db-server:latest

Call a protected endpoint with the same key:

curl -H "X-API-Key: $MCP_API_KEY" http://localhost:8000/mcp/list_tables

Keep the key in a password manager or deployment secret store. Do not commit it to Git, put it in a public image, or include it in logs.

Security Features

• Mandatory HTTP Authentication: Database API routes require X-API-Key; /health remains public for health checks
• Secure Network Default: HTTP mode binds to 127.0.0.1 unless explicitly configured otherwise
• Restricted CORS: Cross-origin access is disabled unless origins are explicitly configured
• 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

Architecture

mcp-db-server/

├── app/ │ ├── init.py # Package initialization │ ├── server.py # FastAPI application and endpoints │ ├── db.py # Database connection and operations │ └── nl_to_sql.py # Natural language to SQL conversion ├── .github/workflows/ │ └── docker-publish.yml # CI/CD pipeline ├── docker-compose.yml # Docker Compose configuration ├── Dockerfile # Container definition