🚀 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:
SELECTqueries return rows. - Database changes:
INSERT,UPDATE,DELETE,CREATE, and more return success status.
- Data retrieval:
- 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.pyshould 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