crystaldba/postgres-mcp

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.
Option 2: Using Python
If you have pipx installed you can install Postgres MCP Pro with:
Otherwise, install Postgres MCP Pro with uv:
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
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
If you are using pipx
If you are using uv
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.