pgmcp
starsforks
How to install pgmcp?
subnetmarco/pgmcp
$git clone https://github.com/subnetmarco/pgmcpPGMCP connects AI assistants to any PostgreSQL database through natural language queries. Ask questions in plain English and get structured SQL results with automatic streaming and robust error handling.
README.md
| 1 | [](https://github.com/subnetmarco/pgmcp/actions/workflows/ci.yml) |
| 2 | [](https://goreportcard.com/report/github.com/subnetmarco/pgmcp) |
| 3 | [](https://opensource.org/licenses/Apache-2.0) |
| 4 | |
| 5 | # PGMCP - PostgreSQL Model Context Protocol Server |
| 6 | |
| 7 | PGMCP connects AI assistants to **any PostgreSQL database** through natural language queries. Ask questions in plain English and get structured SQL results with automatic streaming and robust error handling. |
| 8 | |
| 9 | **Works with**: Cursor, Claude Desktop, VS Code extensions, and any [MCP-compatible client](https://modelcontextprotocol.io/) |
| 10 | |
| 11 | ## Quick Start |
| 12 | |
| 13 | PGMCP connects to **your existing PostgreSQL database** and makes it accessible to AI assistants through natural language queries. |
| 14 | |
| 15 | ### Prerequisites |
| 16 | - PostgreSQL database (existing database with your schema) |
| 17 | - OpenAI API key (optional, for AI-powered SQL generation) |
| 18 | |
| 19 | ### Basic Usage |
| 20 | |
| 21 | ```bash |
| 22 | # Set up environment variables |
| 23 | export DATABASE_URL="postgres://user:password@localhost:5432/your-existing-db" |
| 24 | export OPENAI_API_KEY="your-api-key" # Optional |
| 25 | |
| 26 | # Run server (using pre-compiled binary) |
| 27 | ./pgmcp-server |
| 28 | |
| 29 | # Test with client in another terminal |
| 30 | ./pgmcp-client -ask "What tables do I have?" -format table |
| 31 | ./pgmcp-client -ask "Who is the customer that has placed the most orders?" -format table |
| 32 | ./pgmcp-client -search "john" -format table |
| 33 | ``` |
| 34 | |
| 35 | Here is how it works: |
| 36 | |
| 37 | ``` |
| 38 | 👤 User / AI Assistant |
| 39 | │ |
| 40 | │ "Who are the top customers?" |
| 41 | ▼ |
| 42 | ┌─────────────────────────────────────────────────────────────┐ |
| 43 | │ Any MCP Client │ |
| 44 | │ │ |
| 45 | │ PGMCP CLI │ Cursor │ Claude Desktop │ VS Code │ ... │ |
| 46 | │ JSON/CSV │ Chat │ AI Assistant │ Editor │ │ |
| 47 | └─────────────────────────────────────────────────────────────┘ |
| 48 | │ |
| 49 | │ Streamable HTTP / MCP Protocol |
| 50 | ▼ |
| 51 | ┌─────────────────────────────────────────────────────────────┐ |
| 52 | │ PGMCP Server │ |
| 53 | │ │ |
| 54 | │ 🔒 Security 🧠 AI Engine 🌊 Streaming │ |
| 55 | │ • Input Valid • Schema Cache • Auto-Pagination │ |
| 56 | │ • Audit Log • OpenAI API • Memory Management │ |
| 57 | │ • SQL Guard • Error Recovery • Connection Pool │ |
| 58 | └─────────────────────────────────────────────────────────────┘ |
| 59 | │ |
| 60 | │ Read-Only SQL Queries |
| 61 | ▼ |
| 62 | ┌─────────────────────────────────────────────────────────────┐ |
| 63 | │ Your PostgreSQL Database │ |
| 64 | │ │ |
| 65 | │ Any Schema: E-commerce, Analytics, CRM, etc. │ |
| 66 | │ Tables • Views • Indexes • Functions │ |
| 67 | └─────────────────────────────────────────────────────────────┘ |
| 68 | |
| 69 | External AI Services: |
| 70 | OpenAI API • Anthropic • Local LLMs (Ollama, etc.) |
| 71 | |
| 72 | Key Benefits: |
| 73 | ✅ Works with ANY PostgreSQL database (no assumptions about schema) |
| 74 | ✅ No schema modifications required |
| 75 | ✅ Read-only access (100% safe) |
| 76 | ✅ Automatic streaming for large results |
| 77 | ✅ Intelligent query understanding (singular vs plural) |
| 78 | ✅ Robust error handling (graceful AI failure recovery) |
| 79 | ✅ PostgreSQL case sensitivity support (mixed-case tables) |
| 80 | ✅ Production-ready security and performance |
| 81 | ✅ Universal database compatibility |
| 82 | ✅ Multiple output formats (table, JSON, CSV) |
| 83 | ✅ Free-text search across all columns |
| 84 | ✅ Authentication support |
| 85 | ✅ Comprehensive testing suite |
| 86 | ``` |
| 87 | |
| 88 | ## Features |
| 89 | |
| 90 | - **Natural Language to SQL**: Ask questions in plain English |
| 91 | - **Automatic Streaming**: Handles large result sets automatically |
| 92 | - **Safe Read-Only Access**: Prevents any write operations |
| 93 | - **Text Search**: Search across all text columns |
| 94 | - **Multiple Output Format |
People who liked this also viewed
6 picksType
- mcp-databricks-serverModel Context Protocol (MCP) server for Databricks that empowers AI agents to autonomously interact with Unity Catalog metadata. Enables data discovery, lineage analysis, and intelligent SQL execution. Agents explore catalogs/schemas/tables, understand relationships, discover notebooks/jobs, and execute queries - greatly reducing ad-hoc query time.MCP ServersMar 2026
- mcp-server-qdrantAn official Qdrant Model Context Protocol (MCP) server implementationMCP ServersJul 2026
- mcp-server-odooModel Context Protocol (MCP) server that enables AI assistants to securely interact with Odoo ERP systems through standardized resources and tools for data retrieval and manipulation.MCP ServersJul 2026
- mongodb-mcp-serverA Model Context Protocol server to connect to MongoDB databases and MongoDB Atlas Clusters.MCP ServersJul 2026
- postgres-mcp-serverMCP (Model Context Protocol) Server for postgres DatabaseMCP ServersJul 2025
- mcp-google-sheetsThis MCP server integrates with your Google Drive and Google Sheets, to enable creating and modifying spreadsheets.MCP ServersMay 2026
