Home / MCP / Postgres MCP Server

Postgres MCP Server

A Postgres MCP Server with health checks, index tuning, explain plans, and safe SQL execution for AI-assisted database optimization.

python

1.6kstars

View on GitHub

Installation

Add the following to your MCP client configuration file.

Configuration

View docs

{
    "mcpServers": {
        "postgres_sse": {
            "url": "http://localhost:8000/sse"
        }
    }
}

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, optionally with hypothetical indexes.

get_top_queries

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

analyze_workload_indexes

Analyzes the workload and recommends optimal indexes for heavy queries.

analyze_query_indexes

Analyzes specific queries and recommends index configurations.

analyze_db_health

Performs comprehensive health checks including cache, connections, constraints, and replication health.