Postgres MCP Integration

Date: November 26, 2025
Category: Infrastructure / AI Tools
Status: Active

Overview

Integration of postgres-mcp (CrystalDBA) into the development stack. This MCP server provides PgHero-style database intelligence for AI agents like Claude/Cursor.

What is postgres-mcp?

Postgres MCP Pro is an MCP (Model Context Protocol) server that exposes PostgreSQL performance tools to AI agents. Unlike simple query wrappers, it provides intelligent analysis:

  • Slow Query Detection - Reads from pg_stat_statements
  • Index Recommendations - Uses hypopg for what-if analysis
  • Health Checks - Connection, vacuum, replication status
  • Query Explain - EXPLAIN ANALYZE integration

Docker Compose Setup

Service Definition

# docker-compose.yml
postgres-mcp:
  build:
    context: .
    dockerfile: docker/postgres-mcp.Dockerfile
  container_name: postgres_mcp
  restart: "no"
  command: ["postgres://deploy:deploy@pg:5432/heatwave"]
  depends_on:
    - pg
  stdin_open: true
  tty: true

Dockerfile

# docker/postgres-mcp.Dockerfile
FROM python:3.12-slim
RUN pip install --no-cache-dir uv
RUN uv pip install --system postgres-mcp
ENTRYPOINT ["postgres-mcp"]

Cursor MCP Configuration

// ~/.cursor/mcp.json
{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "exec", "-i", "postgres_mcp",
        "postgres-mcp", "postgres://deploy:deploy@pg:5432/heatwave"
      ]
    }
  }
}

Alternative: Local Installation

For simpler setup without Docker:

# Install uv (Python package manager)
curl -LsSf https://astral.sh/uv/install.sh | sh

# Install postgres-mcp
uv pip install postgres-mcp

# Configure Cursor
# ~/.cursor/mcp.json
{
  "mcpServers": {
    "postgres-mcp": {
      "command": "postgres-mcp",
      "args": ["postgres://deploy:deploy@localhost:5432/heatwave"]
    }
  }
}

Usage with AI Agents

Once configured, you can ask the AI agent:

  • "What are the slowest queries in my database?"
  • "Recommend indexes for the orders table"
  • "Analyze query performance"
  • "Check database health"

Tools Provided

Tool Description
get_slow_queries Finds queries consuming the most time
get_index_recommendations Suggests indexes to improve performance
get_table_stats Shows table sizes, bloat, dead tuples
get_blocking_queries Identifies queries blocking others
explain_query Runs EXPLAIN ANALYZE on queries

Prerequisites

PostgreSQL must have these extensions enabled:

CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS hypopg;  -- Optional, for index analysis

Starting the Service

# Build and start
docker compose build postgres-mcp
docker compose up -d postgres-mcp

# Verify it's running
docker logs postgres_mcp
# Should show: "Successfully connected to database and initialized connection pool"

Security Note

The container runs in UNRESTRICTED mode by default (full read/write access). This is appropriate for development. For production databases, consider:

  1. Using read-only database credentials
  2. Running in RESTRICTED mode (read-only SQL)

See Also