Postgres MCP Pro

Postgres MCP Pro distinguishes itself by providing deterministic tools and classical optimization algorithms rather than relying solely on LLM reasoning for database tuning.

To allow multiple MCP clients to share one remote server, use the Server-Sent Events (SSE) transport by starting the server with the --transport=sse flag.

1. Start the server (e.g., via Docker):

docker run -p 8000:8000 \
  -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
  crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

2. Configure your client:

For Cursor or Cline (mcp.json / cline_mcp_settings.json):

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "url": "http://localhost:8000/sse"
        }
    }
}

For Windsurf (mcp_config.json):

{
    "mcpServers": {
        "postgres": {
            "type": "sse",
            "serverUrl": "http://localhost:8000/sse"
        }
    }
}

The ExplainPlanTool is integrated into the PostgreSQL MCP server and allows you to generate various types of EXPLAIN plans to understand query execution, identify performance bottlenecks, and test hypothetical indexes.

Access this functionality through the MCP API using the explain_query function.

Pull the official Docker image to run Postgres MCP Pro in a containerized environment. This method includes all necessary dependencies and is recommended to avoid Python environment issues.

docker pull crystaldba/postgres-mcp

For advanced features like index tuning and performance analysis, you must enable pg_stat_statements and hypopg on your database.

Cloud Managed Services (AWS RDS, Azure, Google Cloud SQL): Run the following SQL commands:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;

Self-managed Postgres:

1. Ensure pg_stat_statements is listed in shared_preload_libraries in your postgresql.conf.
2. Ensure hypopg is installed on the system via your package manager if it is not included with your Postgres distribution.

To use Postgres MCP Pro with Claude Desktop, edit your claude_desktop_config.json file located at:

• MacOS: ~/Library/Application Support/Claude/claude_desktop_config.json
• Windows: %APPDATA%/Claude/claude_desktop_config.json

Add the server configuration to the mcpServers section. You must provide a DATABASE_URI environment variable containing your Postgres connection string.

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

If you are a developer working on the project or want to install from source, follow these steps to set up your local environment using uv:

1. Install uv using the official installer.
2. Clone the postgres-mcp repository.
3. Install dependencies using uv pip install -e . and uv sync.
4. Start the server by running uv run postgres-mcp followed by your PostgreSQL connection string.

If you prefer running natively via Python, you can install the package using pipx or uv.

Using pipx:

pipx install postgres-mcp

Using uv:

uv pip install postgres-mcp

Postgres MCP Pro supports two access modes via the --access-mode flag to control what the AI agent can do:

• unrestricted: Allows full read/write access to modify data and schema. Best for development.
• restricted: Limits operations to read-only transactions and imposes resource utilization constraints (e.g., execution time). Best for production.

When sorting or filtering data (e.g., 'top-rated' lists) produces unexpected or 'random' results, use the AI agent to analyze the underlying data distribution.

Instead of guessing thresholds (like a minimum number of votes), ask the agent to:

1. Check data presence: Verify if the tables used for sorting actually contain data.
2. Analyze distribution: Get the distribution of values (e.g., num_votes) to determine a statistically sound threshold (e.g., setting a 10K vote minimum) that prevents low-quality data from skewing results.