Skip to main content
Glama
PostgreSQL MCP Server

PostgreSQL MCP Server

by sureshbandi

πŸ”Œ 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.


Related MCP server: PostgreSQL MCP Server for Claude Desktop

πŸ“ 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.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      Not graded
      quality
      D
      maintenance
      Enables secure chat-based interaction with PostgreSQL databases through Claude Desktop. Features GitHub OAuth authentication, role-based access control, and enterprise-grade security for database queries and operations.
      1
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Desktop to interact with PostgreSQL databases through natural language for schema exploration, data analysis, and query execution. Users can search schemas, describe tables, and perform read or write operations without needing to write manual SQL.
      -
    • F
      license
      Not graded
      quality
      D
      maintenance
      Enables Claude Desktop to query a PostgreSQL brand database through MCP. Supports local stdio and remote HTTP/SSE deployments with API key authentication for secure database access.
      -