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:
- Full Server Implementation: Built as a complete server with SSE transport for production use
- Multi-database Support: Connect to multiple PostgreSQL databases simultaneously
- Rich Catalog Information: Extracts and exposes table/column descriptions from the database catalog
- Extension Context: Provides detailed YAML-based knowledge about PostgreSQL extensions like PostGIS and pgvector
- Query Explanation: Includes a dedicated tool for analyzing query execution plans
- 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
Metadata
Release files for iflow-mcp_pg-mcp-server 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| iflow_mcp_pg_mcp_server-0.1.0.tar.gz | 14.3 kB | Without provenance | Details for iflow_mcp_pg_mcp_server-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| iflow_mcp_pg_mcp_server-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for iflow_mcp_pg_mcp_server-0.1.0-py3-none-any.whl |
Total release size: 34.0 kB
Release files / iflow_mcp_pg_mcp_server-0.1.0.tar.gz
| Download URL | iflow_mcp_pg_mcp_server-0.1.0.tar.gz |
|---|---|
| Size | 14.3 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
d15248ab44a4af9e5f9e8fb7ff26575ac27e24f94fabba4d04b472cfc5e45917
|
|
BLAKE2b-256 checksum How to use checksums |
e2957b5bf06fa38a837bef0a34363f12ac1ae965faa1f8834716e1909e529037
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Release files / iflow_mcp_pg_mcp_server-0.1.0-py3-none-any.whl
| Download URL | iflow_mcp_pg_mcp_server-0.1.0-py3-none-any.whl |
|---|---|
| Size | 19.7 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
0da9bf6bf0bbd4e7b571503e085b7370e8ce2095c81419cf2afdc5d5e96ff2a6
|
|
BLAKE2b-256 checksum How to use checksums |
ec59770908b7b4a8175d6b4bc7f7bd436e5c393ac873cfcef68b6d7567b2ff7b
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
uv/0.9.10 {"installer":{"name":"uv","version":"0.9.10"},"python":null,"implementation":{"name":null,"version":null},"distro":{"name":"macOS","version":null,"id":null,"libc":null},"system":{"name":null,"release":null},"cpu":null,"openssl_version":null,"setuptools_version":null,"rustc_version":null,"ci":null}
|
Security for iflow-mcp_pg-mcp-server 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.