🔌 PostgreSQL MCP Server (Python & Docker)

A clean, fully executable implementation of a custom Model Context Protocol (MCP) server built in Python using Anthropic's FastMCP framework. This project connects Claude Desktop directly to a local PostgreSQL database running securely in Docker.

This repository contains all the code and configuration files showcased in the step-by-step YouTube tutorial.

🏗️ Architecture Overview

The connection is established using a simple client-server model defined by the Model Context Protocol: ┌─────────────────┐ JSON-RPC (stdio) ┌───────────────────┐ │ Claude Desktop │ <──────────────────────────> │ Python MCP Server │ │ (MCP Client) │ │ (FastMCP) │ └─────────────────┘ └─────────┬─────────┘ │ SQL │ (Authentication) ▼ ┌───────────────────┐ │ PostgreSQL │ │ (Docker Container)│ └───────────────────┘

• Authentication: The Python script uses a secure username/password credential set to authenticate with the Postgres database.
• Authorization: Claude is authorized strictly to fetch and view products via the @mcp.tool() wrapper. It does not have access or permissions to perform destructive database modifications.

📁 Project Structure

mcp-postgres-demo/
├── db/
│   └── init.sql         # Seed data & table schema definitions
├── docker-compose.yml   # Multi-container local database orchestrator
├── server.py            # FastMCP Server with stdio & SSE transport modes
├── requirements.txt     # Locked project dependencies
└── .gitignore           # Keeps local environments and OS junk out of Git

🚀 Quick Start Guide
1. Clone & Set Up a Virtual Environment
Isolate your Python workspace to avoid dependency version conflicts:
# Clone this repository
git clone [https://github.com/](https://github.com/)<your-username>/claude-postgres-mcp-connector.git
cd claude-postgres-mcp-connector

# Create the virtual environment
python -m venv venv

# Activate it (macOS/Linux)
source venv/bin/activate

# Activate it (Windows PowerShell)
.\venv\Scripts\Activate.ps1

2. Install Project Dependencies
Install the locked dependencies defined in our requirement manifests:

pip install -r requirements.txt
3. Launch the Database (Docker)
We use Docker Compose to spin up a pre-configured Postgres database.
docker-compose up -d
Note: The docker-compose.yml mounts our SQL script using the :ro (Read-Only) volume flag. This is a secure best-practice protecting our local init.sql initialization script from being corrupted or altered by runtime database mutations.