Postgres MCP

A Postgres MCP server with index tuning, explain plans, health checks, and safe sql execution.

Overview • Demo • Quick Start • Technical Notes • MCP API • Related Projects • FAQ

Overview

Postgres MCP Pro is an open source Model Context Protocol (MCP) server built to support you and your AI agents throughout the entire development process—from initial coding, through testing and deployment, and to production tuning and maintenance.

Postgres MCP Pro does much more than wrap a database connection.

Features include:

• 🔍 Database Health - analyze index health, connection utilization, buffer cache, vacuum health, sequence limits, replication lag, and more.
• ⚡ Index Tuning - explore thousands of possible indexes to find the best solution for your workload, using industrial-strength algorithms.
• 📈 Query Plans - validate and optimize performance by reviewing EXPLAIN plans and simulating the impact of hypothetical indexes.
• 🧠 Schema Intelligence - context-aware SQL generation based on detailed understanding of the database schema.
• 🛡️ Safe SQL Execution - configurable access control, including support for read-only mode and safe SQL parsing, making it usable for both development and production.

Postgres MCP Pro supports both the Standard Input/Output (stdio) and Server-Sent Events (SSE) transports, for flexibility in different environments.

For additional background on why we built Postgres MCP Pro, see our launch blog post.

Demo

From Unusable to Lightning Fast

• Challenge: We generated a movie app using an AI assistant, but the SQLAlchemy ORM code ran painfully slow.
• Solution: Using Postgres MCP Pro with Cursor, we fixed the performance issues in minutes.

What we did:

• 🚀 Fixed performance - including ORM queries, indexing, and caching
• 🛠️ Fixed a broken page - by prompting the agent to explore the data, fix queries, and add related content.
• 🧠 Improved the top movies - by exploring the data and fixing the ORM query to surface more relevant results.

See the video below or read the play-by-play.

https://github.com/user-attachments/assets/24e05745-65e9-4998-b877-a368f1eadc13

Quick Start

Prerequisites

Before getting started, ensure you have:

1. Access credentials for your database.
2. Docker or Python 3.12 or higher.

Access Credentials

You can confirm your access credentials are valid by using psql or a GUI tool such as pgAdmin.

Docker or Python

The choice to use Docker or Python is yours. We generally recommend Docker because Python users can encounter more environment-specific issues. However, it often makes sense to use whichever method you are most familiar with.

Installation

Choose one of the following methods to install Postgres MCP Pro:

Option 1: Using Docker

Pull the Postgres MCP Pro MCP server Docker image. This image contains all necessary dependencies, providing a reliable way to run Postgres MCP Pro in a variety of environments.

docker pull crystaldba/postgres-mcp

Option 2: Using Python

If you have pipx installed you can install Postgres MCP Pro with:

pipx install postgres-mcp

Otherwise, install Postgres MCP Pro with uv:

uv pip install postgres-mcp

If you need to install uv, see the uv installation instructions.

Configure Your AI Assistant

We provide full instructions for configuring Postgres MCP Pro with Claude Desktop. Many MCP clients have similar configuration files, you can adapt these steps to work with the client of your choice.

Claude Desktop Configuration

You will need to edit the Claude Desktop configuration file to add Postgres MCP Pro. The location of this file depends on your operating system:

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

You can also use Settings menu item in Claude Desktop to locate the configuration file.

You will now edit the mcpServers section of the configuration file.

If you are using Docker

{
  "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"
      }
    }
  }
}

The Postgres MCP Pro Docker image will automatically remap the hostname localhost to work from inside of the container.

• MacOS/Windows: Uses host.docker.internal automatically
• Linux: Uses 172.17.0.1 or the appropriate host address automatically

If you are using uvx

{
  "mcpServers": {
    "postgres": {
      "command": "uvx",
      "args": [
        "postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

If you are using pipx

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

If you are using uv

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

Connection URI

Replace postgresql://... with your Postgres database connection URI.

Access Mode

Postgres MCP Pro supports multiple access modes to give you control over the operations that the AI agent can perform on the database:

• Unrestricted Mode: Allows full read/write access to modify data and schema. It is suitable for development environments.
• Restricted Mode: Limits operations to read-only transactions and imposes constraints on resource utilization (presently only execution time). It is suitable for production environments.

To use restricted mode, replace --access-mode=unrestricted with --access-mode=restricted in the configuration examples above.

Other MCP Clients

Many MCP clients have similar configuration files to Claude Desktop, and you can adapt the examples above to work with the client of your choice.

• If you are using Cursor, you can use navigate from the Command Palette to Cursor Settings, then open the MCP tab to access the configuration file.
• If you are using Windsurf, you can navigate to from the Command Palette to Open Windsurf Settings Page to access the configuration file.
• If you are using Goose run goose configure, then select Add Extension.
• If you are using Qodo Gen, open the Chat panel, click Connect more tools, click + Add new MCP, then add the new configuration.

SSE Transport

Postgres MCP Pro supports the SSE transport, which allows multiple MCP clients to share one server, possibly a remote server. To use the SSE transport, you need to start the server with the --transport=sse option.

For example, with Docker run:

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

Then update your MCP client configuration to call the the MCP server. For example, in Cursor's mcp.json or Cline's cline_mcp_settings.json you can put:

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

For Windsurf, the format in mcp_config.json is slightly different:

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

Postgres Extension Installation (Optional)

To enable index tuning and comprehensive performance analysis you need to load the pg_stat_statements and hypopg extensions on your database.

• The pg_stat_statements extension allows Postgres MCP Pro to analyze query execution statistics. For example, this allows it to understand which queries are running slow or consuming significant resources.
• The hypopg extension allows Postgres MCP Pro to simulate the behavior of the Postgres query planner after adding indexes.