PGMCP: a Go MCP server that turns plain English into read-only Postgres queries

The gap PGMCP fills between an MCP client and an existing database

Most MCP database servers assume something about your schema, or they expose a fixed set of tools that mirror tables. PGMCP takes the opposite position: it connects to whatever PostgreSQL instance you already have and makes no assumptions about the schema. The README states this directly, listing "Works with ANY PostgreSQL database (no assumptions about schema)" and "No schema modifications required" among its key benefits. That matters if you are pointing an assistant at a database you did not design, such as a vendor schema, an analytics replica, or a legacy CRM.

The intended user is an engineer or analyst who already has an MCP-compatible client open. The README names Cursor, Claude Desktop, VS Code extensions and "any MCP-compatible client". The workflow is conversational: you ask a question in English, the server turns it into SQL, runs it read-only, and returns structured results. The README's own examples are ordinary business questions, such as who the customer is that placed the most orders, or which items in a marketplace have the most reviews. Nothing about the project is aimed at database administrators doing maintenance work. It is aimed at the person who would otherwise write a throwaway query.

How the request flows from chat prompt to Postgres result set

The README's architecture diagram lays out a four-stage path. An MCP client sends a natural language question over Streamable HTTP using the MCP protocol to the PGMCP server. Inside the server, three concerns are separated in the diagram: a security layer (input validation, audit logging, SQL guard), an AI engine (schema cache, OpenAI API calls, error recovery), and a streaming layer (auto-pagination, memory management, connection pool). The server then issues read-only SQL against your database.

The schema cache is the piece that makes the natural language step tractable. Rather than sending your whole catalog on every question, the server keeps a cached picture of the schema and uses it to ground the OpenAI request. The README also calls out "Intelligent query understanding (singular vs plural)" and "PostgreSQL case sensitivity support (mixed-case tables)", which are the two failure modes that most often break naive text-to-SQL on real schemas.

On the database side, the Go module requires github.com/jackc/pgx/v5, so the connection layer is pgx with its puddle-based pool. The MCP layer uses github.com/modelcontextprotocol/go-sdk, and the model calls go through github.com/openai/openai-go/v2. Logging is zerolog. That is a lean dependency set for a server that has to sit between a chat client and a production database.

The README also lists external AI services beyond OpenAI: Anthropic and local LLMs such as Ollama. Treat that as a diagram-level statement rather than a documented integration path. The configuration section only documents OPENAI_API_KEY and OPENAI_MODEL, so if you need a non-OpenAI provider, the README does not tell you how to wire it.

Installing PGMCP and running a first query against your own schema

The README offers three install paths: pre-compiled binaries from GitHub Releases, a Homebrew tap, and a build from source. The Homebrew formula is described as available after the first release, so check the releases page before relying on it. Building from source needs Go and two separate binaries, one for the server and one for the client.

Start by pointing the server at a database you already have. The only required environment variable is DATABASE_URL, and the OpenAI key is optional, which means the server can start without an AI provider configured.

export DATABASE_URL="postgres://user:password@localhost:5432/your-existing-db"
export OPENAI_API_KEY="your-api-key"  # Optional
./pgmcp-server

With the server running, the client binary is what you use to ask questions. The README's first example is deliberately trivial, which is the right way to confirm the connection before trusting generated SQL.

./pgmcp-client -ask "What tables do I have?" -format table

The client takes repeated -ask flags, so you can batch several questions in one invocation, and -format accepts table, json or csv. There is also a separate -search mode that looks across all text columns rather than going through the model.

./pgmcp-client -ask "Show tables" -ask "Count users" -format table
./pgmcp-client -search "john" -format table

If you prefer containers, the Dockerfile builds from scratch and copies in the two binaries, exposing port 8080. The README gives a one-line docker run with DATABASE_URL passed through and 8080 published. A Kubernetes path exists too: create a secret named pgmcp-secret with a database-url key, then apply examples/k8s/. The README does not document what those manifests contain, so read them before applying.

For a local build, the module targets Go 1.26.1 and the README gives the exact commands, including an optional stripped build with -ldflags="-s -w -extldflags=-static" -trimpath.

go build -o pgmcp-server ./server
go build -o pgmcp-client ./client

Where PGMCP stops being the right tool

The read-only guarantee is the project's main selling point and also its hardest boundary. The README describes "Safe Read-Only Access: Prevents any write operations" and a SQL guard in the security layer, but it does not document the guard's implementation. If your workload involves inserting, updating or migrating anything, PGMCP is the wrong layer entirely; it is a query surface, not a database client.

The second boundary is data egress. Generated SQL goes to the OpenAI API, which means schema context leaves your network. The README lists the OpenAI key as optional, which implies a mode without AI generation, but it does not explain what that mode does or how a question is answered without a model. Anyone working under a data residency constraint should treat this as unresolved until they read the server code.

The third is coverage. The README's feature list is about querying: natural language to SQL, streaming, text search, output formats, case sensitivity. There is no documented support for EXPLAIN output, query plan inspection, index advice, connection-level monitoring or schema changes. If you want an assistant to help you tune a slow query, this is not the tool for that job.

Finally, note the licence metadata. The README badge and the LICENSE file point to Apache 2.0, but the repository metadata reports the licence as NOASSERTION. That mismatch is worth resolving internally before you depend on the project, because the two answers imply different obligations.

PGMCP compared with Modelcontextprotocol/server-postgres and pganalyze MCP

The reference point most people arrive with is the official Modelcontextprotocol/server-postgres. That server also connects an MCP client to PostgreSQL, but it takes a different approach to the language step: it exposes a query tool and expects the model to write the SQL itself, with the schema supplied as context. PGMCP moves that work into the server, caching the schema and calling OpenAI to produce the statement. The practical difference is where the prompt engineering lives. With the reference server you tune the client's instructions; with PGMCP you configure OPENAI_MODEL and accept the server's own prompting. PGMCP also adds a dedicated -search mode that bypasses SQL generation for plain text lookups, which the reference server does not have.

A second comparison worth making is with pganalyze MCP, which appears in related searches. That is an observability product, and its MCP surface is oriented around query performance and database health rather than ad hoc business questions. The overlap is small. If your question is "why is this query slow", the pganalyze direction fits better. If your question is "which customers ordered the most last month", PGMCP fits better.

The honest summary is that PGMCP's differentiator is not the protocol, which is shared, but the built-in generation step and the schema cache. That is also where its risk sits: you are trusting a server-side prompt you cannot easily inspect from the outside.

Maintenance, releases and what upgrading actually costs

The repository is not archived, and the last push was on 2026-05-26. The most recent tagged release is v0.3.0 from 2025-09-25. That gap between the last release and the last push is worth noticing: work has continued on main without a corresponding tag, so building from source and running a released binary are not the same thing.

Upgrade cost is low in the ordinary case. The server is a single static binary, the Docker image is built from scratch with no package manager inside it, and the client is a separate binary you can replace independently. There is no database-side migration to run, because the README states that no schema modifications are required. That is the main operational advantage of this design.

The cost that does exist is configuration drift. Environment variables such as OPENAI_MODEL, HTTP_ADDR, HTTP_PATH and AUTH_BEARER carry defaults, and the README does not publish a changelog of when those defaults changed. If you pin a version, read RELEASING.md in the repository before moving. On licensing, the README badge says Apache 2.0 while the repository metadata says NOASSERTION; Apache 2.0 includes an explicit patent grant and requires you to preserve notices, but this is a description of the licence text, not legal advice, and the discrepancy is something your own review process should settle.

Editorial conclusion

Adopt PGMCP if you already run PostgreSQL and want an MCP client to answer questions against it without writing SQL, and if you are comfortable sending schema context and generated queries to the OpenAI API. Do not adopt it if your database holds data that cannot leave your network, or if you need write access, migrations or a query planner UI. Before wiring it into anything shared, verify three things: that the DATABASE_URL role is genuinely read-only, that AUTH_BEARER is set if the server is reachable beyond localhost, and that the SQL guard rejects the statements you care about. The repository's own schema.sql and examples/k8s/ are the fastest way to see what a running instance looks like.

Frequently asked questions

Official sources

1. Issues
2. README
3. Releases
4. subnetmarco/pgmcp on GitHub