pg-mcp

{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"","title":"Introduction","text":""},{"location":"#model-context-protocol-for-postgresql","title":"Model Context Protocol for PostgreSQL","text":"<p>pg-mcp is an ecosystem for connecting LLMs (Large Language Models) with PostgreSQL databases, enabling natural language queries through a standardized protocol.</p>"},{"location":"#overview","title":"Overview","text":"<p>The pg-mcp project consists of two main components:</p> <ol> <li> <p>pg-mcp-server: A server component that provides a standardized API for querying PostgreSQL databases through the Model Context Protocol (MCP).</p> </li> <li> <p>pg-mcp-client: A web-based client application that allows users to bring their own LLM API key and query PostgreSQL databases using natural language through an intuitive UI.</p> </li> </ol> <p>The key benefit of this setup is that you never send your data to the LLM.</p>"},{"location":"#screenshots","title":"Screenshots","text":""},{"location":"#features","title":"Features","text":"<ul> <li>Natural Language Querying: Ask questions about your data in plain English</li> <li>Multiple LLM Support: Works with Anthropic (Claude), Google (Gemini), and OpenAI (untested) models</li> <li>Interactive Web UI: Clean, responsive interface built with modern web technologies</li> <li>Standardized Protocol: Built on the Model Context Protocol for AI systems</li> <li>Database Schema Awareness: Automatically analyzes database structure for accurate SQL generation</li> </ul>"},{"location":"#getting-started","title":"Getting Started","text":"<p>If you're new to pg-mcp, check out the quickstart guides:</p> <ul> <li>Server Quickstart</li> <li>Client Quickstart</li> </ul>"},{"location":"overview/","title":"Overview","text":"<p>pg-mcp-server is a multi-tenant Model Context Protocol server which bridges the connection between LLM Agents and PostgreSQL databases. Built with FastMCP, the official MCP Python SDK, and AsyncPG, the MCP server runs in \"server-mode\", communicating with agents via HTTP Server Side Events (SSE) and accepting PostgreSQL connection strings while providing read-only query access to connected databases.</p> <p>pg-mcp-client is full web application which encompasses both the UI and an agent which can communicate with the LLM of your choice via API </p>"},{"location":"overview/#system-architecture","title":"System Architecture","text":"<pre><code>graph TD\n classDef clientColor fill:#a7f3d0,stroke:#0478573\n classDef serverColor fill:#ddd6fe\n UI &lt;--&gt; Agents[\"pg-mcp-agent\"]\n Agents &lt;--_HTTP/SSE_--&gt; MCP[\"**pg-mcp-server**\"]\n MCP &lt;--_TCP/IP_--&gt; DB[(PostgreSQL Databases)]\n Agents &lt;-- _REST API_ --&gt; LLM[\"LLM\"]\n\n subgraph Client[\"**pg-mcp-client**\"]\n UI\n Agents\n end\n\n class Client clientColor\n class MCP serverColor</code></pre> <p>In this architecture: - pg-mcp-client provides a user interface and agent integration - pg-mcp-server connects to your PostgreSQL databases - LLM providers (Anthropic, OpenAI, Google) translate natural language to SQL</p>"},{"location":"overview/#how-it-works","title":"How it Works","text":"<p>MCP Servers provide additional tools and resources available to agents in order to enhance their capabilities. When supplied with a valid PostgreSQL database connection string, pg-mcp-server exposes enriched database schema information to agents, providing them with context about the structure and purpose of the database. </p> <p>Agents can take advantage of a well-documented database as pg-mcp-server will provide table and column comments/descriptions alongside the schema. This facilitates better understanding of user prompts from the standpoint of the database's business domain.</p> <p>pg-mcp-client stores API Keys and connection strings in the user's browser</p>"},{"location":"overview/#key-features","title":"Key Features","text":"<ul> <li>Multi-Database Support: Connect to multiple PostgreSQL databases simultaneously</li> <li>Rich Catalog Information: Extract and expose table/column descriptions from the database catalog</li> <li>Extension Context: Detailed knowledge about PostgreSQL extensions like PostGIS and pgvector</li> <li>Query Explanation: Dedicated tool for analyzing query execution plans</li> <li>Secure Connection Management: Proper lifecycle for database connections with secure connection ID handling</li> <li>Natural Language to SQL: Built-in prompt to convert natural language to SQL queries</li> </ul>"},{"location":"overview/#tools-and-resources","title":"Tools and Resources","text":""},{"location":"overview/#tools","title":"Tools","text":"<ul> <li><code>connect</code> - creates the connection from the connection string and returns a UUID <code>conn_id</code></li> <li><code>disconnect</code> - closes the database connection associated with the <code>conn_id</code></li> <li><code>pg_query</code> - executes a read-only SQL query</li> <li><code>pg_explain</code> - provides the query execution plan for a query</li> </ul>"},{"location":"overview/#resource-templates","title":"Resource Templates","text":"<p>Resource templates mirror the hierarchical object structure of PostgreSQL databases, and present them in a RESTful resource manner as URIs:</p> <ul> <li><code>pgmcp://{conn_id}/</code> - Comprehensive database information</li> <li><code>pgmcp://{conn_id}/schemas</code> - List all schemas</li> <li><code>pgmcp://{conn_id}/schemas/{schema}/tables</code> - List tables in a schema</li> <li><code>pgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns</code> - Get columns for a table</li> <li><code>pgmcp://{conn_id}/schemas/{schema}/extensions</code> - List extensions in a schema</li> </ul>"},{"location":"overview/#prompts","title":"Prompts","text":"<ul> <li><code>nl_to_sql</code> - Convert natural language questions to SQL queries</li> </ul>"},{"location":"quickstart/client/","title":"pg-mcp-client","text":""},{"location":"quickstart/client/#installation","title":"Installation","text":""},{"location":"quickstart/client/#prerequisites","title":"Prerequisites","text":"<ul> <li>Python 3.13+</li> <li>A running pg-mcp-server</li> <li>API key from one of the supported AI providers</li> </ul>"},{"location":"quickstart/client/#using-docker","title":"Using Docker","text":"<pre><code># Clone the repository\ngit clone https://github.com/stuzero/pg-mcp-client.git\ncd pg-mcp-client\n\n# Create a .env file with your application secret\necho \"APPLICATION_SECRET=your_secure_random_string\" &gt; .env\n\n# Build and run with Docker\ndocker-compose up -d\n</code></pre>"},{"location":"quickstart/client/#manual-installation","title":"Manual Installation","text":"<pre><code># Clone the repository\ngit clone https://github.com/stuzero/pg-mcp-client.git\ncd pg-mcp-client\n\n# Install dependencies and create a virtual environment ( .venv )\nuv sync\n\n# Activate the virtual environment\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Create a .env file with your application secret\necho \"APPLICATION_SECRET=your_secure_random_string\" &gt; .env\n\n# Run the application\npython -m client.app\n</code></pre>"},{"location":"quickstart/client/#configuration","title":"Configuration","text":"<ol> <li>Access the web interface at http://localhost:8080</li> <li>Navigate to the Settings page and configure:</li> <li>LLM Provider: Select from Anthropic (Claude), Gemini, or OpenAI</li> <li>LLM API Key: Your API key for the selected provider</li> <li>PG-MCP Server URL: The URL of your PG-MCP server's SSE endpoint (e.g., http://localhost:8000/sse)</li> <li>Database URL: PostgreSQL connection string for the target database</li> </ol>"},{"location":"quickstart/client/#usage","title":"Usage","text":"<ol> <li>After configuring settings, go to the Query page</li> <li>Enter your question in natural language (e.g., \"Show me the top 10 customers by revenue\")</li> <li>Click \"Execute Query\"</li> <li>View the generated SQL and query results</li> </ol>"},{"location":"quickstart/client/#example-queries","title":"Example Queries","text":"<p>Try these example queries to get started:</p> <ul> <li>\"List all tables in the database\"</li> <li>\"Show me the first 5 rows from the customers table\"</li> <li>\"What were the total sales by month in 2023?\"</li> <li>\"Find customers who haven't placed an order in the last 3 months\"</li> <li>\"What product categories have the highest profit margin?\"</li> </ul>"},{"location":"quickstart/client/#supported-llm-models","title":"Supported LLM Models","text":"<ul> <li>Anthropic: Claude 3.7 Sonnet (recommended for best results)</li> <li>Google: Gemini 2.0 Flash</li> <li>OpenAI: GPT-4o Mini (untested)</li> </ul> <p>For more details, visit the pg-mcp-client GitHub repository.</p>"},{"location":"quickstart/server/","title":"pg-mcp-server","text":""},{"location":"quickstart/server/#installation","title":"Installation","text":""},{"location":"quickstart/server/#prerequisites","title":"Prerequisites","text":"<ul> <li>Python 3.13+</li> <li>PostgreSQL database(s)</li> </ul>"},{"location":"quickstart/server/#using-docker","title":"Using Docker","text":"<pre><code># Clone the repository\ngit clone https://github.com/stuzero/pg-mcp-server.git\ncd pg-mcp-server\n\n# Build and run with Docker Compose\ndocker-compose up -d\n</code></pre>"},{"location":"quickstart/server/#manual-installation","title":"Manual Installation","text":"<pre><code># Clone the repository\ngit clone https://github.com/stuzero/pg-mcp-server.git\ncd pg-mcp-server\n\n# Install dependencies and create a virtual environment ( .venv )\nuv sync\n\n# Activate the virtual environment\nsource .venv/bin/activate # On Windows: .venv\\Scripts\\activate\n\n# Run the server\npython -m server.app\n</code></pre>"},{"location":"quickstart/server/#testing-the-server","title":"Testing the Server","text":"<p>The repository includes test scripts to verify server functionality:</p> <pre><code># Basic server functionality test\npython test.py \"postgresql://username:password@hostname:port/database\"\n\n# Claude-powered natural language to SQL conversion\npython example-clients/claude_cli.py \"Show me the top 5 customers by total sales\"\n</code></pre> <p>The <code>claude_cli.py</code> script requires environment variables:</p> <pre><code># .env file\nDATABASE_URL=postgresql://username:password@hostname:port/database\nANTHROPIC_API_KEY=your-anthropic-api-key\nPG_MCP_URL=http://localhost:8000/sse\n</code></pre>"},{"location":"quickstart/server/#using-with-claude-desktop","title":"Using with Claude Desktop","text":"<p>Add the following to your <code>claude_desktop_config.json</code> file <pre><code>{\n \"mcpServers\": {\n \"pg-mcp-server\": {\n \"command\": \"npx\",\n \"args\": [\n \"mcp-remote\",\n \"http://localhost:8000/sse\"\n ]\n }\n }\n}\n</code></pre></p>"},{"location":"quickstart/server/#using-with-ai-agents","title":"Using with AI Agents","text":"<p>Example prompt for use with agents:</p> <pre><code>Use the PostgreSQL MCP server to analyze the database. \nAvailable tools:\n- connect: Register a database connection string and get a connection ID\n- disconnect: Close a database connection\n- pg_query: Execute SQL queries using a connection ID\n- pg_explain: Get query execution plans\n\nYou can explore schema resources via:\npgmcp://{conn_id}/schemas\npgmcp://{conn_id}/schemas/{schema}/tables\npgmcp://{conn_id}/schemas/{schema}/tables/{table}/columns\n</code></pre>"}]}