PG-MCP-Client

A web-based client application for the PostgreSQL Model Context Protocol (PG-MCP) server that allows users to query databases using natural language.

More info on the pg-mcp project here:

https://stuzero.github.io/pg-mcp/

Overview

PG-MCP-Client provides a user-friendly web interface for interacting with PostgreSQL databases through the PG-MCP server. It leverages AI language models to translate natural language questions into SQL queries, making database exploration accessible to users without SQL expertise.

The client connects to a PG-MCP server, which provides database schema information and query execution capabilities, while an AI provider (Anthropic, Google, or OpenAI) handles the natural language understanding and SQL generation.

Features

• Natural Language Interface: Query your PostgreSQL database using plain English
• Multiple LLM Support: Compatible with Anthropic (Claude), Google (Gemini), and OpenAI models
• Interactive UI: Clean, responsive web interface built with Tailwind CSS and HTMX
• Database Schema Exploration: Automatically retrieves and uses database schema for accurate query generation
• Query Visualization: Displays generated SQL and query results in a formatted table
• Configurable Settings: Easy configuration of API keys and connection details

Screenshot

Installation

Prerequisites

• Python 3.13+
• A running PG-MCP server
• API key from one of the supported AI providers:
  • Anthropic
  • Google AI (Gemini)
  • OpenAI

Using Docker

# Clone the repository
git clone https://github.com/stuzero/pg-mcp-client.git
cd pg-mcp-client

# Create a .env file with your application secret
echo "APPLICATION_SECRET=your_secure_random_string" > .env

# Build and run with Docker
docker-compose up -d

Manual Installation

This project uses uv for dependency management:
uv Installation Instructions

# Clone the repository
git clone https://github.com/stuzero/pg-mcp-client.git
cd pg-mcp-client

# Install dependencies and create a virtual environment ( .venv )
uv sync

# Activate the virtual environment
source .venv/bin/activate

# Create a .env file with your application secret
echo "APPLICATION_SECRET=your_secure_random_string" > .env

# Run the application
python -m client.app

Usage

1. Access the web interface at http://localhost:8080
2. Navigate to the Settings page and configure:
   • LLM Provider (Anthropic, Gemini, or OpenAI)
   • LLM API Key
   • PG-MCP Server URL (e.g., http://localhost:8000/sse)
   • PostgreSQL Connection String
3. Go to the Query page
4. Enter your question in natural language (e.g., “Show me the top 10 customers by revenue”)