# MCP Server for Database (PostgreSQL and MySQL)
![Python](https://img.shields.io/badge/Python-3.12-blue.svg?logo=python&logoColor=white)
![PostgreSQL](https://img.shields.io/badge/PostgreSQL-Data-4169E1.svg?logo=postgresql&logoColor=white)
![MySQL](https://img.shields.io/badge/MySQL-Database-4479A1.svg?logo=mysql&logoColor=white)
![Docker](https://img.shields.io/badge/Docker-Container-2496ED.svg?logo=docker&logoColor=white)
![HTTP](https://img.shields.io/badge/Transport-HTTP/SSE-0052CC.svg?logo=google-cloud&logoColor=white)

A Model Context Protocol server that provides access to PostgreSQL or MySQL. This server enables LLMs to inspect database schemas and execute queries.

## Key Features

* **Autonomous Schema Discovery:** AI agents can list tables and inspect columns to understand your data structure without manual intervention.
* **Security First (Read-Only):** Strictly enforces read-only access. Only `SELECT`, `WITH`, `SHOW`, `DESCRIBE`, and `EXPLAIN` statements are permitted.
* **Multi-Database Support:** Seamlessly connects to **PostgreSQL** and **MySQL** (SQL Server & SQLite support coming soon).
* **Flexible Deployment:** Supports multiple transport modes including **stdio** (for local IDEs), **HTTP/SSE** (for cloud APIs), and **Docker**.


## Available Tools

The server exposes the following tools to AI clients:

| Tool | Capability | User Intent Example |
| :--- | :--- | :--- |
| `list-tables` | Lists all accessible tables in the database. | "What tables are available in the schema?" |
| `describe-table` | Retrieves column details, data types, and constraints. | "Tell me about the 'Inventory' table structure." |
| `execute-query` | Executes safe, read-only SQL queries to fetch live data. | "Who are the top 5 customers by revenue today?" |


## Architecture Overview
```mermaid
graph TD
    A[AI Assistant] -->|MCP Protocol| B{MCP Server}
    subgraph "Deployment Modes"
        B -->|stdio| C[Local IDE: VSCode/Cursor]
        B -->|HTTP/SSE| D[Cloud/Remote API]
        B -->|Docker| E[Containerized Service]
    end
    B -->|Read-Only SQL| F[(PostgreSQL / MySQL)]
```

> [!TIP]
> **Dive Deeper:** For a detailed breakdown of the communication flow, sequence diagrams, and deployment strategies, please check out our **[Full Architecture Guide](./docs/ARCHITECTURE.md)**

## Quick Start

### 1. Installation

```bash
pip install -r requirements.txt

```

### 2. Run with Docker (Recommended)

Update the `DATABASE_URI` in `docker-compose.yaml` and run:

```bash
docker compose up --build

```

### 3. Run Locally

```bash
# PostgreSQL
python -m src --connection-string "postgresql://user:pass@localhost:5432/db"

# MySQL
python -m src --connection-string "mysql+pymysql://user:pass@localhost:3306/db"

```



## AI Client Configuration

### Claude Desktop

Add this to your `claude_desktop_config.json`:

```json
{
  "mcpServers": {
    "sql-intelligence": {
      "command": "python",
      "args": ["-m", "src", "--connection-string", "your_connection_string"],
      "cwd": "/path/to/project"
    }
  }
}

```

### VSCode (Cline / Roo Code)

Create `.vscode/mcp.json` in your workspace:

```json
{
  "mcpServers": {
    "database": {
      "command": "python",
      "args": [
        "-m", "src",
        "--connection-string", "postgresql://user:pass@localhost:5432/mydb"
      ],
      "cwd": "/path/to/mcp-for-database"
    }
  }
}

```

## Security Guardrails

The server utilizes a strict Regex-based validation layer. Any query that does not start with an authorized read-only keyword is blocked immediately to prevent unauthorized data modification.



## Roadmap

* [ ] Support for **SQL Server** and **SQLite**.
* [ ] Integration of **Audit Logs** for tracking AI query behaviors.
* [ ] Semantic Search capabilities combining SQL and Vector DB.



## Project Demo
You can watch the full demo of this MCP Server for Database on YouTube: [Watch here](https://youtu.be/5PqgcyrvY9A)