pg

This PG-MCP server provides a Model Context Protocol interface for PostgreSQL databases, enabling AI agents to connect to one or more databases, discover their schemas, and perform read-only queries and explanations via a consistent toolset. Core tools include: connect to register a database connection string and receive a secure connection ID, disconnect to close a connection, pg_query to execute read-only SQL against a specified connection, and pg_explain to obtain query execution plans in JSON format. You can navigate the database structure through resources that expose schemas, tables, and columns with descriptive metadata, as well as access sample data and approximate row counts. The server also includes extension context (e.g., PostGIS, pgvector) described in YAML to help agents reason about specialized data types and functions. To use with agents, first establish a connection, then address resources using the provided connection ID, for example pgmcp://{conn_id}/schemas or pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns. If you need deeper insights into a query, run pg_explain to retrieve the execution plan in JSON, which agents can analyze to optimize subsequent queries.

Prerequisites:

• Python 3.13+ installed on the host
• Access to a PostgreSQL database or databases

Option A: Using Docker (recommended for quick start)

1. Clone the repository and navigate to the project directory: git clone https://github.com/stuzero/pg-mcp-server.git cd pg-mcp-server
2. Build and run with Docker Compose: docker-compose up -d

Option B: Manual installation (local development)

1. Clone the repository: git clone https://github.com/stuzero/pg-mcp-server.git cd pg-mcp-server
2. Create and activate a virtual environment (example for Unix-like systems): python -m venv .venv source .venv/bin/activate
3. Install dependencies (adjust as needed for your environment): pip install -r requirements.txt
4. Run the server: python -m server.app

Environment setup (required for operation):

• Ensure DATABASE_URL points to a reachable PostgreSQL instance
• (Optional) Set ANTHROPIC_API_KEY if Claude-based tooling is used by the client
• Expose PG_MCP_URL if external clients must reach the MCP SSE endpoint

Notes:

• The server runs in read-only mode by default; write actions should be restricted by design.
• For production deployments, consider using a reverse proxy and proper authentication/authorization around the MCP endpoints.

Tips and common considerations:

• Use the connect tool to register each PostgreSQL connection and obtain a connection ID for subsequent requests.
• The system supports multi-database scenarios; you can maintain multiple connections and target resources per connection ID.
• If you encounter authentication or connection errors, verify network reachability to the PostgreSQL hosts and ensure the credentials in DATABASE_URL are correct.
• For extension context (PostGIS, pgvector), make sure the target databases have the relevant extensions installed so that the MCP can surface accurate descriptions and capabilities.
• When testing with agents, you can start with simple queries via pg_query to validate access, then progressively explore schemas, tables, and columns using the discovered resource URIs.
• If using Claude or other natural language tooling, ensure that environment variables (like ANTHROPIC_API_KEY) are configured and that the PG_MCP_URL points to your MCP server’s SSE endpoint.