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

Related MCP server: PostgreSQL MCP Server

✨ 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.