# 🚀 PostgreSQL MCP Server

A lightweight **Model Context Protocol (MCP) server** for executing PostgreSQL queries.

This project enables an MCP-compatible client to run SQL queries (both `SELECT` and non-`SELECT`) directly on a PostgreSQL database. The server supports both standard input/output and HTTP (REST API) communication modes.

***

## 🧩 What is MCP (Model Context Protocol)?

MCP is a universal protocol for connecting external tools, data sources, and services to AI models in a **standardized way**.

- **Why MCP?**
MCP eliminates the need for custom integrations per tool, providing a **common API** for interacting with various resources.
- **How does this project fit in?**
This repo gives you an **MCP server for PostgreSQL**:
    - Send SQL queries from any MCP-compatible client.
    - Receive results in structured JSON.
    - Seamlessly use PostgreSQL as a knowledge base or app datastore.

***

## ✨ Features

- Execute direct PostgreSQL queries via MCP.
- Supports:
    - **Data retrieval**: `SELECT` queries return rows.
    - **Database changes**: `INSERT`, `UPDATE`, `DELETE`, `CREATE`, and more return success status.
- Dual operation modes:
    - `stdio` (standard in/out)
    - `http` (REST API server)
- Structured logging with **loguru**.
- Built for educational, hackable use (not hardened for production).

***

## ⚡ Requirements

- Python **3.9+**
- A running **PostgreSQL** database
- Dependencies:
    - `psycopg2` (SQL driver)
    - `loguru` (logging)
    - `mcp` (Model Context Protocol library)

***

## 📂 Project Structure

```
.
├── .venv/              # Local virtual environment (should be gitignored)
├── .gitignore          # Ignore rules for git
├── .python-version     # Python version file
├── code.txt            # (Optional: dev notes or scratch work)
├── main.py             # CLI entry point to start the server
├── pyproject.toml      # Project dependencies and metadata
├── README.md           # This documentation file
├── server.py           # PostgreSQL MCP server implementation
└── uv.lock             # Dependency lockfile for reproducible installs
```


***

## 🛠 Setup \& Usage

### 1. Clone the repository

```bash
git clone https://github.com/<your-username>/<your-repo-name>.git
cd <your-repo-name>
```


### 2. Install dependencies

```bash
uv sync
```


### 3. Run the server

**HTTP mode:**

```bash
python server.py --mode http --port 9000
```

**Stdio mode (for integration as a tool):**

```bash
python server.py --mode stdio
```


***

## 🧰 Development Notes

- All logic is contained in `server.py`.
- `main.py` should be a minimal CLI entry point that parses arguments and starts the server.
- Feel free to reorganize into a package structure if your codebase grows.

***

## 👨‍💻 Author

Created with ❤️ by **Loki** 

- 📧 Email: logeshwaranshanmugam21@gmail.com
- 🔗 LinkedIn: [Logeshwaran Shanmugam](https://www.linkedin.com/in/logeshwaran-shanmugam)

***

**Tip:**
Remember to update your `.gitignore` to exclude `.venv/`, `__pycache__/`, and other cache files for a clean repository.

***
Happy querying