Registry / database / postgres-mcp

postgres-mcp

JSON →
library0.3.0pypypi✓ verified 85d ago

PostgreSQL Tuning and Analysis Tool (Multi-Cluster Performance), currently at version 0.3.0. It's a command-line utility and a Python library designed to help analyze and optimize PostgreSQL database performance by providing recommendations and insights. Its release cadence is irregular, typical for a community-driven tool in its early stages.

pip install postgres-mcp
INSTALL
IMPORT
SIG · POSTGRES-MCP
P
postgres-mcp
databasepythonv0.3.0
Install
11.6s avg
Import
Disk
151MB
Pass rate
4/ 10
Env Coverage4 / 10
glibc
3.93.13
musl
3.93.13
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
musl
glibc
py 3.10
✕ build_error
✕ build_error
py 3.11
✕ build_error
✕ build_error
py 3.12
✓ —
✓ 11.35s
py 3.13
✓ —
✓ 11.75s
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
Debug
Known issues
breakingAs a pre-1.0 library (version 0.x.x), `postgres-mcp`'s API is subject to change without strict backward compatibility guarantees. Expect potential breaking changes in minor releases.
fix
Always pin the exact version in your `requirements.txt` or `pyproject.toml` (e.g., `postgres-mcp==0.3.0`) and review release notes carefully before upgrading.
affects: <1.0.0
gotcha`postgres-mcp` primarily operates as a command-line tool. While programmatic access to its components (like `ConnectionManager`, `Recommender`, `Analyzer`) is possible, the documentation often focuses on CLI usage. Direct programmatic usage requires familiarity with its internal module structure.
fix
Refer to the source code (especially `src/postgres_mcp/mcp.py` for how the CLI uses the library) to understand the intended usage of internal classes and functions.
affects: All versions
gotchaFor `postgres-mcp` to provide comprehensive analysis and recommendations, the connecting PostgreSQL user typically requires more than just basic read-only access. It needs permissions to query system views and potentially execute functions like `pg_stat_statements` (if enabled).
fix
Ensure your database user has sufficient privileges, e.g., membership in the `pg_monitor` role or specific `SELECT` grants on views like `pg_stat_activity`, `pg_settings`, `pg_stat_bgwriter`, etc.
affects: All versions
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.
Agent activity
25 hits · last 30 days
node
20
OpenAI (training)
2
Amazon
1
Resources
postgres-mcp — pip install postgres-mcp · libregistry