MCP Database Guardrail
by ernestoh0183
README.md
# π‘οΈ MCP Database Guardrail
[](https://opensource.org/licenses/MIT)
[](https://www.python.org/)
[](https://modelcontextprotocol.io/)
[](https://www.4ruy.com)
> **Enterprise-grade Model Context Protocol (MCP) servers for secure, read-only database exploration (SQLite, PostgreSQL, MySQL) with AST guardrails and zero-trust controls.**
Official companion open-source repository for the **4Ruy.com** engineering series on AI Skills and Model Context Protocol:
* Read the technical article: [Β«CΓ³mo Darle Manos a tu IA: QuΓ© es Model Context Protocol (MCP) y GuΓa PrΓ‘ctica para Conectar Herramientas y Bases de DatosΒ»](https://www.4ruy.com/es/como-conectar-ia-herramientas-bases-datos-mcp/)
* English version: [Β«Giving Hands to Your AI: What is Model Context Protocol (MCP) and a Practical Guide to Connect Tools and DatabasesΒ»](https://www.4ruy.com/how-to-connect-ai-tools-databases-mcp/)
---
## π‘ The Problem: The "House Key" vs. The "Hotel Keycard"
Giving Large Language Models (LLMs) direct, unconstrained database credentials is like handing a stranger the master key to your entire house: they can open personal drawers, read sensitive records, or demolish a wall with a sledgehammer.
**MCP Database Guardrail** implements the **Hotel Keycard Architecture**:
1. **Scoped Room Access:** The AI agent is only granted access to whitelisted tables and schemas, isolating internal administration and security metadata.
2. **Read-Only Observation:** The agent can inspect the table schema and execute analytical read operations (`SELECT`, `WITH`), but is structurally blocked from destructive actions (`INSERT`, `UPDATE`, `DELETE`, `DROP`, `ALTER`, `TRUNCATE`).
3. **Resource Safeguards:** Enforces hard limits (`LIMIT 50`) and strict execution timeouts (`10s`) to prevent runaway Cartesian joins or memory exhaustion.
```
βββββββββββββββββββββββββββββββββββ
β AI Host / Agent Client β
β (Claude Desktop, Cursor, etc.) β
ββββββββββββββββββ¬βββββββββββββββββ
β JSON-RPC 2.0 (MCP Protocol)
βΌ
ββββββββββββββββββββββββββββββββββββββββββββββββββββββββββ
β MCP Database Guardrail Server β
β β
β βββ Resource: Database Schema Inspection (Read-Only) β
β βββ Tool: Safe SQL Execution (AST Guardrail) β
β βββ Prompt: Business KPI Analysis Template β
ββββββββββββββββββ¬ββββββββββββββββββββββββββββββββββββββββ
β Strict SELECT / Read-Only Transaction
βΌ
βββββββββββββββββββββββββββββββββββ
β Target Database Engine β
β (SQLite / PostgreSQL / MySQL) β
βββββββββββββββββββββββββββββββββββ
```
---
## π Key Features
* **Zero-Dependency Quickstart:** Run locally in 10 seconds with `server_sqlite.py` (automatically seeds an `empresa_demo.db` dataset).
* **Multi-Engine Support:** Ready-to-use production servers for **SQLite**, **PostgreSQL**, and **MySQL**.
* **AST & Token Guardrails:** Programmatic rejection of dangerous keywords, multi-statement injection attempts, and DDL mutations.
* **Automatic `LIMIT` Enforcement:** Appends `LIMIT 50` if omitted by the model, preventing buffer overflows.
* **Native MCP Components:**
* **Resources (`schema`):** Allows models to understand relational schemas without consuming execution tokens blindly.
* **Tools (`ejecutar_consulta_segura`):** Controlled query execution returning structured JSON with latency metrics.
* **Prompts (`asistente_kpis_negocio`):** Standard operating guidelines for autonomous data analysis.
---
## π¦ Installation & Setup
### 1. Clone the repository
```bash
git clone https://github.com/ernestoh0183/mcp-database-guardrail.git
cd mcp-database-guardrail
```
### 2. Create virtual environment & install dependencies
```bash
python -m venv .venv
# On Windows:
.venv\Scripts\activate
# On Linux/macOS:
source .venv/bin/activate
pip install -e .
```
---
## π οΈ Configuration for AI Clients
Add the server to your favorite MCP-compatible client configuration file:
### Claude Desktop (`claude_desktop_config.json`)
* **macOS:** `~/Library/Application Support/Claude/claude_desktop_config.json`
* **Windows:** `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"sqlite-guardrail": {
"command": "python",
"args": [
"/absolute/path/to/mcp-database-guardrail/server_sqlite.py"
],
"env": {
"SQLITE_DB_PATH": "empresa_demo.db"
}
}
}
}
```
### Cursor (`.cursor/mcp.json` or Settings -> Features -> MCP)
```json
{
"mcpServers": {
"postgres-guardrail": {
"command": "python",
"args": [
"/absolute/path/to/mcp-database-guardrail/server_postgres.py"
],
"env": {
"PG_HOST": "localhost",
"PG_PORT": "5432",
"PG_DATABASE": "empresa_prod",
"PG_USER": "readonly_ai_user",
"PG_PASSWORD": "your_secure_password_here",
"PG_SCHEMA": "public"
}
}
}
}
```
---
## π§ͺ Quick Test in Terminal
You can test the server directly with the official MCP Inspector:
```bash
npx @modelcontextprotocol/inspector python server_sqlite.py
```
Then ask your AI agent:
> *"Show me the top 3 best-selling products this month and their total revenue."*
The model will:
1. Inspect `sqlite://schema` to locate the `pedidos` and `productos` tables.
2. Draft a `SELECT` query with `JOIN` and `GROUP BY`.
3. Invoke `ejecutar_consulta_segura` through the MCP protocol.
4. Return an executive summary with verified, grounded figures.
---
## π License & Attribution
This project is licensed under the **MIT License** - see the [LICENSE](LICENSE) file for details.
* **Author:** Rodrigo Ernesto HernΓ‘ndez Buitrago
* **Website:** [https://www.4ruy.com](https://www.4ruy.com)
* **LinkedIn:** [Rodrigo Ernesto HernΓ‘ndez Buitrago](https://www.linkedin.com/in/rodrigo-ernesto-hernandez-buitrago-786b09113/)
This server cannot be deployed
Maintenance
ActivityMaintained
ResponsivenessNo recent community issues