Postgres MCP Pro

Postgres MCP Pro is an MCP server for PostgreSQL that provides health checks, index tuning, query plan analysis, and safe SQL execution to empower AI agents throughout development and production tuning.

How to use

You connect an MCP client to Postgres MCP Pro to perform health checks, analyze slow queries, generate index recommendations, and safely execute SQL. Start with a local or remote server, then configure your MCP client to point at the server. You can choose between a local, stdio-based setup or a remote, SSE-like transport, depending on your environment and needs.

How to install

Prerequisites include a running PostgreSQL database and either Docker or Python with the uv runtime. You should also ensure you have access credentials for your database.

# Docker option: pull the MCP server image
docker pull crystaldba/postgres-mcp

# Optional: run your server with unrestricted access via Docker (example)
docker run -i --rm -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname crystaldba/postgres-mcp --access-mode=unrestricted

# pipx option: install the MCP server with pipx
pipx install postgres-mcp

# Start or configure as needed for your environment

# uv option: install and run the server with uv
uv pip install postgres-mcp

uv run postgres-mcp "postgres://username:password@localhost:5432/dbname"

Additional setup and configuration

Configure your MCP client to connect to the server. The examples show three ways to run the server locally and provide a configuration JSON you can place in your MCP client settings.

SSE transport and multi-client setup

Postgres MCP Pro supports the SSE transport, allowing multiple MCP clients to share one server. Start the server with the transport option and provide the client with the SSE URL.

Postgres extensions (optional)

To enable extended health checks and tuning capabilities, load the pg_stat_statements and hypopg extensions on your database. Use CREATE EXTENSION IF NOT EXISTS pg_stat_statements; and CREATE EXTENSION IF NOT EXISTS hypopg; as needed.

Usage examples (typical tasks)

Check database health, analyze slow queries, generate index recommendations, and optimize specific queries using the provided tools.

Development notes

If you are developing locally, you can follow the build/run flow described in the setup steps and run the server with the final start command shown in your chosen approach.

Available tools

list_schemas

Lists all database schemas available in the PostgreSQL instance.

list_objects

Lists database objects (tables, views, sequences, extensions) within a specified schema.

get_object_details

Provides information about a specific database object, such as a table's columns, constraints, and indexes.

execute_sql

Executes SQL statements on the database with read-only limitations in restricted mode.

explain_query

Gets the execution plan for a SQL query, including hypothetical indexes to simulate performance changes.

get_top_queries

Reports the slowest SQL queries based on total execution time using pg_stat_statements data.

analyze_workload_indexes

Analyzes the workload to identify resource-intensive queries and recommends indexes.

analyze_query_indexes

Analyzes a list of queries (up to 10) and recommends optimal indexes.

analyze_db_health

Performs comprehensive health checks including buffer cache, connections, index health, vacuum health, and more.