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

The gap PGMCP fills between a Postgres schema and a chat client

Most people who want to ask questions about a database end up writing SQL, or asking someone who can. PGMCP targets the case where the person asking is an AI assistant and the person answering is an existing PostgreSQL instance. The README states the server connects to your existing database and makes it accessible to AI assistants through natural language queries, and that it works with any PostgreSQL database with no assumptions about schema and no schema modifications. The audience is therefore not the data team that already has a BI tool. It is engineers and analysts who have an MCP-compatible client such as Cursor, Claude Desktop or a VS Code extension open all day and want the database reachable from that same window. The repository also ships a small CLI client, which matters because it gives you a way to exercise the server without wiring up a full MCP client first.

How the request travels: client, MCP server, OpenAI, Postgres

The architecture diagram in the README shows four layers. An MCP client sends a question over streamable HTTP using the MCP protocol to the PGMCP server. Inside the server the README lists three groups of components: security (input validation, audit log, SQL guard), an AI engine (schema cache, OpenAI API, error recovery), and streaming (auto-pagination, memory management, connection pool). The server then issues read-only SQL against your PostgreSQL database. The schema cache is the piece worth noting. Natural language to SQL depends on the model knowing your table and column names, and re-reading the catalog on every question would be wasteful, so the server keeps that information. The README does not state the cache invalidation policy, which means a schema change made while the server is running has undocumented behaviour. If you add a column and the assistant keeps ignoring it, the cache is the first thing to check, and the README gives you no command to flush it.

Getting it running: binaries, environment variables, client calls

The documented path is a pre-compiled binary from GitHub Releases. On macOS or Linux the README gives tar xzf pgmcp_*.tar.gz, then cd into the extracted directory, then ./pgmcp-server. Two binaries are produced by the build: pgmcp-server and pgmcp-client, built with go build -o pgmcp-server ./server and go build -o pgmcp-client ./client. The stripped variant adds -ldflags="-s -w -extldflags=-static" -trimpath. Configuration is entirely environment variables. DATABASE_URL is required. OPENAI_API_KEY is optional, and the README labels it as being for AI-powered SQL generation, which implies the server has some non-AI path, though the README does not describe what that path does. OPENAI_MODEL defaults to gpt-4o-mini. HTTP_ADDR defaults to :8080 and HTTP_PATH defaults to /mcp, so the MCP endpoint is http://localhost:8080/mcp unless you change it. AUTH_BEARER is optional and sets a bearer token for authentication. Leaving it unset on a reachable host means the endpoint is unauthenticated, and the README does not say otherwise. Docker is documented as docker run -e DATABASE_URL="postgres://user:pass@host:5432/db" -p 8080:8080 ghcr.io/subnetmarco/pgmcp:latest, and there are Kubernetes manifests under examples/k8s/ with a secret created via kubectl create secret generic pgmcp-secret --from-literal=database-url="...". Once the server is up, the client takes -ask for a question, -search for free-text search across text columns, and -format for table, json or csv. Flags repeat: ./pgmcp-client -ask "Show tables" -ask "Count users" -format table.

Read-only is the load-bearing claim, and the README is thin on how it is enforced

The README calls the access read-only and says it prevents any write operations, and the architecture diagram labels the database link "Read-Only SQL Queries". This is the claim the whole tool rests on. If it holds, pointing PGMCP at a production replica is a reasonable thing to do. The README does not explain the mechanism. It lists a "SQL Guard" component and an audit log, and stops there. There is no description of whether the guard parses statements, matches prefixes, or relies on database-level grants, and no list of what it rejects. That gap matters because natural language to SQL is not deterministic. A question phrased as "clean up the duplicate rows" could plausibly generate a DELETE. Whether the guard catches that, and whether it catches it before or after the statement reaches Postgres, is not stated. If you deploy this, do not take the read-only claim on trust. Connect it to a role that only has SELECT grants, and test the guard with a prompt that tries to write. The README's own example list is entirely read-shaped, which is consistent but not proof.

Where PGMCP is the wrong tool

The OpenAI dependency is the first boundary. SQL generation goes through the OpenAI API by default, so questions and, presumably, schema details leave your network. The README mentions Anthropic and local LLMs such as Ollama in the diagram's "External AI Services" box, but the documented configuration exposes only OPENAI_API_KEY and OPENAI_MODEL. There is no documented variable for pointing at a local endpoint. A team with a no-egress policy cannot use the documented setup as written. The second boundary is analytical workload. The README advertises auto-pagination and streaming for large result sets, and the client renders tables, JSON or CSV, but nothing in the material describes cost estimation, query timeouts, or a statement timeout setting. A natural language question that translates into a full scan of a large table will run, and the README does not say what stops it. The third boundary is schema complexity. The schema cache plus a small default model is a reasonable combination for a database with a dozen tables and clear naming. For a warehouse with hundreds of tables, near-duplicate names and heavy use of views, the README offers no guidance on how the model is given enough context to choose correctly.

Alternatives: what changes if you drop the natural language layer

The obvious comparison is the Postgres MCP server in the official modelcontextprotocol/servers repository. The difference is in where the intelligence sits. PGMCP puts a schema cache and an OpenAI call inside the server so the client can send English. The official server exposes the database as tools and lets the client's model write the SQL. That shifts the failure mode: with PGMCP, a bad query is the server's translation problem; with the tool-style server, it is the assistant's reasoning problem, and you can see the SQL in the conversation before it runs. PGMCP's bundled CLI is closer in spirit to psql or a notebook, and for a one-off question that is often the cheaper route. There is also no documented read-only mode in the official server, so if safety is the deciding factor, PGMCP's stated read-only design is the differentiator, provided you verify it.

Maintenance, releases and what the licence line actually says

The repository shows one release, v0.3.0, dated 2025-09-25, and the last push is 2026-05-26, so the project is active between releases rather than release-driven. The version number suggests the API surface is still moving, and the README's Homebrew section says "Available after first release", which reads as stale text given that v0.3.0 exists. Treat the CLI flags and environment variables as unstable across minor versions and pin a binary rather than tracking main. The licence is the part to read carefully. The repository metadata reports NOASSERTION, while the README badge points at Apache 2.0 and links to opensource.org/licenses/Apache-2.0. Those two signals disagree, and the metadata is what automated tooling will see. If you are packaging PGMCP into a product, confirm the actual LICENSE file in the repository rather than trusting the badge, and note that this is a description of what the material shows, not legal advice. There is no stated commercial support, no changelog beyond the release list, and no documented upgrade procedure.

Editorial conclusion

Adopt PGMCP if you already run PostgreSQL, want an MCP client such as Cursor or Claude Desktop to answer questions about that schema, and can accept that generated SQL is validated rather than guaranteed correct. Do not adopt it if you need write access, if your data cannot be sent to an external model provider, or if you expect the repository to tell you how the SQL guard actually works, because the README does not. Before connecting a production database, verify three things yourself: that the SQL guard rejects statements beyond SELECT, that AUTH_BEARER is set so the /mcp endpoint is not open, and which OpenAI model OPENAI_MODEL resolves to in your deployment.

Official sources

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