PostgreSQL MCP Server

# 🚀 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