mcp-db

The mcp-db MCP server exposes your relational databases (PostgreSQL and MySQL) via a Safe, NLP-powered API. It converts natural language questions into SQL queries and returns structured results, enabling AI agents to explore data without direct SQL manipulation. The API is read-only by default, with query validation and result limits to protect your data. Use the endpoints to health-check the service, list tables, inspect schemas, run natural language queries, and fetch sample data from tables. You can run the server locally in development mode or deploy it via Docker Compose for production-like environments. To interact, provide a properly formatted NLP query through the /mcp/query endpoint and receive a JSON response containing the SQL-derived results.

Prerequisites:

• Python 3.11+ installed on your system
• Access to a PostgreSQL or MySQL database (locally or in the cloud)
• Optional: Docker and Docker Compose if you prefer containerized deployment

Step-by-step installation:

1. Clone the repository: git clone https://github.com/Souhar-dya/mcp-db-server.git cd mcp-db-server

2. Create and activate a Python virtual environment (recommended): python3 -m venv venv source venv/bin/activate

3. Install dependencies: pip install -r requirements.txt

4. Configure environment variables (example): export DATABASE_URL="postgresql+asyncpg://user:password@localhost:5432/dbname" export HOST="0.0.0.0" export PORT="8000"

5. Run the server: python -m app.server

Optional Docker deployment:

1. Build and run with Docker Compose (recommended for production-like setups): docker-compose up --build

2. If using a direct Docker run (cloud or local): docker run -d
   -p 8000:8000
   -e DATABASE_URL="<your_database_url>"
   souhardyak/mcp-db-server:latest

Tips and considerations:

• The server enforces read-only operations by default; dangerous SQL operations are rejected for safety.
• Ensure your DATABASE_URL uses the appropriate driver prefix (postgresql+asyncpg for PostgreSQL, mysql+pymysql for MySQL).
• If you deploy behind a reverse proxy, adjust HOST/PORT accordingly and ensure network access to the database.
• For cloud DBs, SSL handling is configured by the server; use the standard URL scheme and rely on the server’s SSL behavior.
• Use the /health endpoint to verify service health and /mcp/list_tables to explore available data before querying.
• If you encounter connection issues, verify firewall rules, credentials, and that the database accepts connections from your host.
• The sample database in the repo provides customers, orders, and related data to test queries locally.