What is Pg Mcp Server

pg-mcp-server is a Model Context Protocol (MCP) server designed for PostgreSQL databases, enabling AI agents to discover, connect, query, and comprehend database structures through a resource-oriented architecture.

Use cases

Use cases include AI agents querying PostgreSQL databases for insights, developers analyzing query performance, and data scientists exploring database schemas and data.

How to use

To use pg-mcp-server, register your PostgreSQL connection strings to obtain a secure connection ID. You can then execute read-only SQL queries and analyze query execution plans using the provided tools.

Key features

Key features include multi-database support, rich catalog information, detailed extension context, robust connection management, and dedicated query tools for execution analysis and data access.

Where to use

pg-mcp-server can be utilized in fields such as data analytics, AI development, and database management, where understanding and interacting with PostgreSQL databases is essential.

PostgreSQL Model Context Protocol (PG-MCP) Server

A Model Context Protocol (MCP) server for PostgreSQL databases with enhanced capabilities for AI agents.

More info on the pg-mcp project here:

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

Overview

PG-MCP is a server implementation of the Model Context Protocol for PostgreSQL databases. It provides a comprehensive API for AI agents to discover, connect to, query, and understand PostgreSQL databases through MCP’s resource-oriented architecture.

This implementation builds upon and extends the reference Postgres MCP implementation with several key enhancements:

1. Full Server Implementation: Built as a complete server with SSE transport for production use
2. Multi-database Support: Connect to multiple PostgreSQL databases simultaneously
3. Rich Catalog Information: Extracts and exposes table/column descriptions from the database catalog
4. Extension Context: Provides detailed YAML-based knowledge about PostgreSQL extensions like PostGIS and pgvector
5. Query Explanation: Includes a dedicated tool for analyzing query execution plans
6. Robust Connection Management: Proper lifecycle for database connections with secure connection ID handling

Features

Connection Management

• Connect Tool: Register PostgreSQL connection strings and get a secure connection ID
• Disconnect Tool: Explicitly close database connections when done
• Connection Pooling: Efficient connection management with pooling

Query Tools

• pg_query: Execute read-only SQL queries using a connection ID
• pg_explain: Analyze query execution plans in JSON format

Schema Discovery Resources

• List schemas with descriptions
• List tables with descriptions and row counts
• Get column details with data types and descriptions
• View table constraints and indexes
• Explore database extensions

Data Access Resources

• Sample table data (with pagination)
• Get approximate row counts

Extension Context

Built-in contextual information for PostgreSQL extensions like:

• PostGIS: Spatial data types, functions, and examples
• pgvector: Vector similarity search functions and best practices

Additional extensions can be easily added via YAML config files.

Installation

Prerequisites

• Python 3.13+
• PostgreSQL database(s)

Using Docker

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

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

Manual Installation

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

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

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the server
python -m server.app

Usage

Testing the Server

The repository includes test scripts to verify server functionality:

# Basic server functionality test
python test.py "postgresql://username:password@hostname:port/database"

# Claude-powered natural language to SQL conversion
python example-clients/claude_cli.py "Show me the top 5 customers by total sales"

The claude_cli.py script requires environment variables:

# .env file
DATABASE_URL=postgresql://username:password@hostname:port/database
ANTHROPIC_API_KEY=your-anthropic-api-key
PG_MCP_URL=http://localhost:8000/sse

For AI Agents

Example prompt for use with agents:

Use the PostgreSQL MCP server to analyze the database. 
Available tools:
- connect: Register a database connection string and get a connection ID
- disconnect: Close a database connection
- pg_query: Execute SQL queries using a connection ID
- pg_explain: Get query execution plans

You can explore schema resources via:
pgmcp://{conn_id}/schemas
pgmcp://{conn_id}/schemas/{schema}/tables
pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns

A comprehensive database description is available at this resource:
pgmcp://{conn_id}/

Architecture

This server is built on:

• MCP: The Model Context Protocol foundation
• FastMCP: Python library for MCP
• asyncpg: Asynchronous PostgreSQL client
• YAML: For extension context information

Security Considerations

• The server runs in read-only mode by default (enforced via transaction settings)
• Connection details are never exposed in resource URLs, only opaque connection IDs
• Database credentials only need to be sent once during the initial connection

Contributing

Contributions are welcome! Areas for expansion:

• Additional PostgreSQL extension context files
• More schema introspection resources
• Query optimization suggestions