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

🛡️ Postgres MCP Pro (Secured by Aegis Zero-Trust)

This is the mathematically secured distribution of crystaldba/postgres-mcp, designed for Enterprise Production environments (SOC2/HIPAA).

⚠️ Security Warning: Exposing raw PostgreSQL MCP servers directly to LLMs presents a critical prompt-injection liability.

This distribution embeds the Aegis Ed25519 Edge Proxy directly into the Docker pipeline. It intercepts the JSON-RPC payload and mathematically blocks unauthorized DROP, DELETE, and ALTER commands in <2ms before they ever reach the database connection.

Zero-Trust Deployment

1. Generate your Ed25519 Capability Token at the Aegis Cloud Console.
2. Run the secure stack:

docker-compose up -d

All MCP traffic must now be routed through http://localhost:8080 with a valid X-Aegis-IBCT signature.

Overview

⚖️ Open-Source Attribution: This repository is an independent, mathematically hardened distribution of the official CrystalDBA Postgres MCP Server. It is maintained by the Aegis Security Protocol team to provide a SOC2/HIPAA-compliant deployment pathway for enterprise environments.

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.