This project provides a PostgreSQL Model Context Protocol (PG-MCP) server, designed for AI agents to interact with PostgreSQL databases. It offers enhanced capabilities over the reference implementation, enabling AI agents to discover, connect, query, and understand database schemas and extensions, with a focus on read-only operations for safety.

How It Works

PG-MCP is built on the Model Context Protocol (MCP) and leverages FastMCP for its Python implementation. It uses asyncpg for asynchronous PostgreSQL interaction and Server-Sent Events (SSE) for transport. The server exposes database resources like schemas, tables, and columns, and includes contextual information for extensions such as PostGIS and pgvector via YAML configuration. It also features a tool for analyzing query execution plans.

Quick Start & Requirements

• Installation: Clone the repository and run via Docker Compose (docker-compose up -d) or manually install dependencies (uv sync), activate a virtual environment, and run the server (python -m server.app).
• Prerequisites: Python 3.13+, PostgreSQL database(s).
• Usage: Includes test scripts (test.py) and an example client (claude_cli.py) for natural language to SQL conversion, requiring ANTHROPIC_API_KEY and DATABASE_URL environment variables.
• Documentation: https://stuzero.github.io/pg-mcp/

Highlighted Details

• Full server implementation with SSE transport for production.
• Supports connecting to multiple PostgreSQL databases simultaneously.
• Provides rich catalog information, including table/column descriptions and extension context (PostGIS, pgvector).
• Includes a pg_explain tool for analyzing query execution plans.
• Robust connection management with pooling and secure connection ID handling.

Maintenance & Community

The project is maintained by stuzero. Contributions are welcome, with suggested areas for expansion including more extension contexts and schema introspection resources.

Licensing & Compatibility

The repository does not explicitly state a license in the provided README. Users should verify licensing for commercial or closed-source integration.

Limitations & Caveats

The server runs in read-only mode by default, enforced via transaction settings. While it aims for robust connection management, users should be aware of the security implications of exposing database credentials during the initial connection setup.