🚀 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

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

2. Install dependencies

uv sync

3. Run the server

HTTP mode:

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

Stdio mode (for integration as a tool):

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

---

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

---

Happy querying