Install & Compatibility
Where this runs
tested against v0.3.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.9
✕ build_error
✕ build_error
151MB installed
● package 151MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
main
✓ from postgres_mcp import main
✗ from postgres_mcp.connections import ConnectionManager
server
✓ from postgres_mcp import server
database_health
✓ from postgres_mcp import database_health
This quickstart demonstrates how to programmatically use `postgres-mcp` to connect to a PostgreSQL database and fetch performance recommendations using the `ConnectionManager` and `Recommender` classes. It requires setting database connection details via environment variables or hardcoding them (not recommended for production).
import os
from postgres_mcp.connections import ConnectionManager
from postgres_mcp.recommender import Recommender
# Ensure these environment variables are set or provide default values
DB_HOST = os.environ.get('PG_MCP_DB_HOST', 'localhost')
DB_PORT = int(os.environ.get('PG_MCP_DB_PORT', 5432))
DB_USER = os.environ.get('PG_MCP_DB_USER', 'postgres')
DB_PASS = os.environ.get('PG_MCP_DB_PASS', '') # Consider using an actual password or no password if allowed
DB_NAME = os.environ.get('PG_MCP_DB_NAME', 'postgres')
if not DB_PASS and DB_USER != 'postgres': # Simple check for non-default user requiring password
print("Warning: DB_PASS environment variable not set. Connection might fail if user requires a password.")
try:
# Initialize connection manager
conn_manager = ConnectionManager(
host=DB_HOST,
port=DB_PORT,
user=DB_USER,
password=DB_PASS,
dbname=DB_NAME
)
# Initialize the recommender with the connection manager
recommender = Recommender(conn_manager)
# Get recommendations
print(f"Fetching recommendations for {DB_USER}@{DB_HOST}:{DB_PORT}/{DB_NAME}...")
recommendations = recommender.get_recommendations()
print("\nPostgreSQL Recommendations:")
if recommendations:
for category, recs in recommendations.items():
print(f"[{category.upper()}]")
for key, value in recs.items():
print(f" - {key}: {value}")
else:
print("No specific recommendations found (this might be normal for a healthy DB or small workload).")
except Exception as e:
print(f"\nAn error occurred during recommendation generation: {e}")
print("Please ensure:")
print("1. Your PostgreSQL server is running and accessible from this machine.")
print("2. The provided database connection details (host, port, user, password, dbname) are correct.")
print("3. The database user has sufficient permissions to query system catalog views (e.g., pg_stat_activity, pg_settings).")
postgres-mcp --version
Upgrade
Version history
0.3.0latest on PyPI · released May 16, 2025
Audit
Dependencies
psycopg2-binaryrequiredPostgreSQL database adapter for connecting to the database.
SQLAlchemyrequiredORM and SQL toolkit used for database interaction.