Skip to content
Back to search

pg-mcp-server

PostgreSQL Model Context Protocol (PG-MCP) Server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/stuzero--pg-mcp-server/badge.svg)](/listings/stuzero--pg-mcp-server)

HTML

<a href="/listings/stuzero--pg-mcp-server"><img src="/api/listings/stuzero--pg-mcp-server/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Prerequisites

- Python 3.13+ - PostgreSQL database(s)

Using Docker

# Clone the repository
git clone https://github.com/stuzero/pg-mcp-server.git
cd pg-mcp-server

# Build and run with Docker Compose
docker-compose up -d

Manual Installation

# Clone the repository
git clone https://github.com/stuzero/pg-mcp-server.git
cd pg-mcp-server

# Install dependencies and create a virtual environment ( .venv )
uv sync

# Activate the virtual environment
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Run the server
python -m server.app

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 158 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # PostgreSQL Model Context Protocol (PG-MCP) Server
  2. A Model Context Protocol (MCP) server for PostgreSQL databases with enhanced capabilities for AI agents.
  3. More info on the pg-mcp project here:
  4. ### [https://stuzero.github.io/pg-mcp/](https://stuzero.github.io/pg-mcp/)
  5. ## Overview
  6. PG-MCP is a server implementation of the [Model Context Protocol](https://modelcontextprotocol.io) for PostgreSQL databases. It provides a comprehensive API for AI agents to discover, connect to, query, and understand PostgreSQL databases through MCP's resource-oriented architecture.
  7. This implementation builds upon and extends the [reference Postgres MCP implementation](https://github.com/modelcontextprotocol/servers/tree/main/src/postgres) with several key enhancements:
  8. 1. **Full Server Implementation**: Built as a complete server with SSE transport for production use
  9. 2. **Multi-database Support**: Connect to multiple PostgreSQL databases simultaneously
  10. 3. **Rich Catalog Information**: Extracts and exposes table/column descriptions from the database catalog
  11. 4. **Extension Context**: Provides detailed YAML-based knowledge about PostgreSQL extensions like PostGIS and pgvector
  12. 5. **Query Explanation**: Includes a dedicated tool for analyzing query execution plans
  13. 6. **Robust Connection Management**: Proper lifecycle for database connections with secure connection ID handling
  14. ## Features
  15. ### Connection Management
  16. - **Connect Tool**: Register PostgreSQL connection strings and get a secure connection ID
  17. - **Disconnect Tool**: Explicitly close database connections when done
  18. - **Connection Pooling**: Efficient connection management with pooling
  19. ### Query Tools
  20. - **pg_query**: Execute read-only SQL queries using a connection ID
  21. - **pg_explain**: Analyze query execution plans in JSON format
  22. ### Schema Discovery Resources
  23. - List schemas with descriptions
  24. - List tables with descriptions and row counts
  25. - Get column details with data types and descriptions
  26. - View table constraints and indexes
  27. - Explore database extensions
  28. ### Data Access Resources
  29. - Sample table data (with pagination)
  30. - Get approximate row counts
  31. ### Extension Context
  32. Built-in contextual information for PostgreSQL extensions like:
  33. - **PostGIS**: Spatial data types, functions, and examples
  34. - **pgvector**: Vector similarity search functions and best practices
  35. Additional extensions can be easily added via YAML config files.
  36. ## Installation
  37. ### Prerequisites
  38. - Python 3.13+
  39. - PostgreSQL database(s)
  40. ### Using Docker
  41. ```bash
  42. # Clone the repository
  43. git clone https://github.com/stuzero/pg-mcp-server.git
  44. cd pg-mcp-server
  45. # Build and run with Docker Compose
  46. docker-compose up -d
  47. ```
  48. ### Manual Installation
  49. ```bash
  50. # Clone the repository
  51. git clone https://github.com/stuzero/pg-mcp-server.git
  52. cd pg-mcp-server
  53. # Install dependencies and create a virtual environment ( .venv )
  54. uv sync
  55. # Activate the virtual environment
  56. source .venv/bin/activate # On Windows: .venv\Scripts\activate
  57. # Run the server
  58. python -m server.app
  59. ```
  60. ## Usage
  61. ### Testing the Server
  62. The repository includes test scripts to verify server functionality:
  63. ```bash
  64. # Basic server functionality test
  65. python test.py "postgresql://username:password@hostname:port/database"
  66. # Claude-powered natural language to SQL conversion
  67. python example-clients/claude_cli.py "Show me the top 5 customers by total sales"
  68. ```
  69. The `claude_cli.py` script requires environment variables:
  70. ```
  71. # .env file
  72. DATABASE_URL=postgresql://username:password@hostname:port/database
  73. ANTHROPIC_API_KEY=your-anthropic-api-key
  74. PG_MCP_URL=http://localhost:8000/sse
  75. ```
  76. ### For AI Agents
  77. Example prompt for use with agents:
  78. ```
  79. Use the PostgreSQL MCP server to analyze the database.
  80. Available tools:
  81. - connect: Register a database connection string and get a connection ID
  82. - disconnect: Close a database connection
  83. - pg_query: Execute SQL queries using a connection ID
  84. - pg_explain: Get query execution plans
  85. You can explore schema resources via:
  86. pgmcp://{conn_id}/schemas
  87. pgmcp://{conn_id}/schemas/{schema}/tables
  88. pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns
  89. A comprehensive database description is available at this resource:
  90. pgmcp://{conn_id}/
  91. ```
  92. ## Architecture
  93. This server is built on:
  94. - **MCP**: The Model Context Protocol foundation
  95. - **FastMCP**: Python library for MCP
  96. - **asyncpg**: Asynchronous PostgreSQL client
  97. - **YAML**: For extension context information
  98. ## Security Considerations
  99. - The server runs in read-only mode by default (enforced via transaction settings)
  100. - Connection details are never exposed in resource URLs, only opaque connection IDs
  101. - Database credentials only need to be sent once during the initial connection
  102. ## Contributing
  103. Contributions are welcome! Areas for expansion:
  104. - Additional PostgreSQL extension context files
  105. - More schema introspection resources
  106. - Query optimization suggestions

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.