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

```text
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.