Server data from the Official MCP Registry
MCP server for SQLite, PostgreSQL, and MySQL with natural language to SQL and direct SQL tooling.
MCP server for SQLite, PostgreSQL, and MySQL with natural language to SQL and direct SQL tooling.
Valid MCP server (2 strong, 4 medium validity signals). 15 known CVEs in dependencies (1 critical, 11 high severity) Imported from the Official MCP Registry.
5 files analyzed · 15 issues found
Security scores are indicators to help you make informed decisions, not guarantees. Always review permissions before connecting any MCP server.
This plugin requests these system permissions. Most are normal for its category.
Unverified package source
We couldn't verify that the installable package matches the reviewed source code. Proceed with caution.
Set these up before or after installing:
Environment variable: DATABASE_URL
From the project's GitHub README.
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.
| Endpoint | Method | Description |
|---|---|---|
/health | GET | Health check and service status |
/mcp/list_tables | GET | List all available tables with column counts |
/mcp/describe/{table_name} | GET | Get detailed schema for a specific table |
/mcp/query | POST | Execute natural language queries |
/mcp/tables/{table_name}/sample | GET | Get sample data from a table |
Clone and start the services:
git clone https://github.com/Souhar-dya/mcp-db-server.git
cd mcp-db-server
docker-compose up --build
Test the endpoints:
# Health check
curl http://localhost:8000/health
# List tables
curl http://localhost:8000/mcp/list_tables
# Describe a table
curl http://localhost:8000/mcp/describe/customers
# Natural language query
curl -X POST "http://localhost:8000/mcp/query" \
-H "Content-Type: application/json" \
-d '{"nl_query": "show top 5 customers by total orders"}'
Prerequisites:
Install dependencies:
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
The project includes a sample database with realistic e-commerce data:
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"}'
| Variable | Description | Default |
|---|---|---|
DATABASE_URL | Full database connection URL | postgresql+asyncpg://postgres:postgres@localhost:5432/postgres |
DB_HOST | Database host | localhost |
DB_PORT | Database port | 5432 |
DB_USER | Database username | postgres |
DB_PASSWORD | Database password | postgres |
DB_NAME | Database name | postgres |
HOST | Server host | 0.0.0.0 |
PORT | Server port | 8000 |
# 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
```bash
# 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-modeparameter in the URL is ignored by the driver, but SSL is always enabled in the MCP server for cloud connections.- For PostgreSQL, use
sslmode=requirefor cloud DBs. For MySQL, just use the standard URL; SSL is handled automatically.- If you see errors about
ssl-modeorsslmode, check your URL and ensure you are using the correct driver prefix (mysql+aiomysqlorpostgresql+asyncpg).
# 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 run -d \
-p 8000:8000 \
-e DATABASE_URL="<your_cloud_database_url>" \
souhardyak/mcp-db-server:latest
connect() got an unexpected keyword argument 'ssl-mode', ignore it: SSL is still enabled.mysql+aiomysql in the URL for async support.
## 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
## 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 ├── init_db.sql # Sample database schema and data ├── requirements.txt # Python dependencies └── README.md # This file
## Model Context Protocol (MCP) Integration
This server is designed to work seamlessly with MCP-compatible AI agents:
1. **Standardized Endpoints**: RESTful API following MCP conventions
2. **Structured Responses**: JSON responses optimized for AI consumption
3. **Error Handling**: Consistent error messages and status codes
4. **Documentation**: OpenAPI/Swagger documentation available at `/docs`
## Publish To VS Code MCP Store (Registry)
VS Code MCP gallery uses MCP Registry metadata. This repository now includes
`server.json` for registry publication.
### 1) Build and publish Docker image
```bash
docker build -t souhardyak/mcp-db-server:1.3.1 .
docker push souhardyak/mcp-db-server:1.3.1
server.json is configured for an OCI package and stdio transport:
name: io.github.Souhar-dya/mcp-db-serverregistryType: ociidentifier: docker.io/souhardyak/mcp-db-server:1.3.1The Dockerfile includes registry ownership annotation:
io.modelcontextprotocol.server.name=io.github.Souhar-dya/mcp-db-serverInstall publisher and publish metadata:
mcp-publisher login github
mcp-publisher publish
After publishing, users can discover/install it from MCP-compatible clients, including VS Code MCP experiences that read from the registry.
{
"servers": {
"mcp-db-server": {
"type": "stdio",
"command": "docker",
"args": [
"run",
"--rm",
"-i",
"-e",
"DATABASE_URL=sqlite+aiosqlite:////data/default.db",
"souhardyak/mcp-db-server:1.3.1"
]
}
}
}
Use the dedicated Docker smoke test in tests/docker:
python tests/docker/smoke_test.py
This verifies Docker daemon access, image build, container startup, and health status.
# Pull the latest image
docker pull souhardyak/mcp-db-server:latest
# Run with your database
docker run -d \
-p 8000:8000 \
-e DATABASE_URL="your_database_url_here" \
souhardyak/mcp-db-server:latest
apiVersion: apps/v1
kind: Deployment
metadata:
name: mcp-db-server
spec:
replicas: 3
selector:
matchLabels:
app: mcp-db-server
template:
metadata:
labels:
app: mcp-db-server
spec:
containers:
- name: mcp-db-server
image: souhardyak/mcp-db-server:latest
ports:
- containerPort: 8000
env:
- name: DATABASE_URL
valueFrom:
secretKeyRef:
name: db-secret
key: url
---
apiVersion: v1
kind: Service
metadata:
name: mcp-db-server-service
spec:
selector:
app: mcp-db-server
ports:
- port: 80
targetPort: 8000
type: LoadBalancer
# Start test database
docker-compose up postgres -d
# Wait for database to be ready
sleep 10
# Run tests
python -m pytest tests/ -v
# Test health endpoint
curl http://localhost:8000/health
# Test table listing
curl http://localhost:8000/mcp/list_tables
# Test natural language query
curl -X POST "http://localhost:8000/mcp/query" \
-H "Content-Type: application/json" \
-d '{"nl_query": "show me all customers from California"}'
git checkout -b feature/amazing-feature)git commit -m 'Add some amazing feature')git push origin feature/amazing-feature)This project is licensed under the Apache License 2.0 - see the LICENSE file for details.
from db import DatabaseManager to failmcp_server.py now uses robust path resolution that works both locally and in Docker containersCould not locate column in row for column 'column_name' error with MySQL databasesdescribe_table method to use index-based row access for better SQLAlchemy compatibilitystr can't be used in 'await' expression error in MCP server⭐ If this project helped you, please consider giving it a star!
Be the first to review this server!
by Modelcontextprotocol · Developer Tools
Web content fetching and conversion for efficient LLM usage
by Modelcontextprotocol · Developer Tools
Read, search, and manipulate Git repositories programmatically
by Toleno · Developer Tools
Toleno Network MCP Server — Manage your Toleno mining account with Claude AI using natural language.
by mcp-marketplace · Developer Tools
Create, build, and publish Python MCP servers to PyPI — conversationally.
by Microsoft · Content & Media
Convert files (PDF, Word, Excel, images, audio) to Markdown for LLM consumption
by mcp-marketplace · Developer Tools
Scaffold, build, and publish TypeScript MCP servers to npm — conversationally