PGMCP
A Go MCP server that lets an agent ask a PostgreSQL database questions in plain language and returns the query result
- 540 ★ on the repository
- Last commit
Extended access
Why this level
- The DATABASE_URL string gives the server read access to your PostgreSQL database, including personal data in tables
- Writes are stopped by a query filter, so for safety also grant the database user read-only rights on the PostgreSQL side
- The text of your questions goes to the external OpenAI API
Install
- Works in
Manual install
docker run -e DATABASE_URL="postgres://user:pass@host:5432/db" -p 8080:8080 ghcr.io/subnetmarco/pgmcp:latestRuns the ready image. For SQL generation add the OPENAI_API_KEY variable.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- The DATABASE_URL string gives the server read access to your PostgreSQL database, including personal data in tables
- Writes are stopped by a query filter, so for safety also grant the database user read-only rights on the PostgreSQL side
- The text of your questions goes to the external OpenAI API
This is third-party code. Review the repository files before installing.
What it does
PGMCP connects an AI assistant to an existing PostgreSQL database. The Go server takes a question in plain language, uses a language model to turn it into a SQL query, runs it and returns a table, JSON or CSV. No schema changes are needed: any database works, including tables with mixed-case names. The agent gets three tools. `ask` answers a question and streams large result sets on its own, `search` looks for text across all text columns, and `stream` pages through very large results. The server listens for HTTP on port 8080 at `/mcp`, and Cursor, Claude Desktop and other MCP-capable clients connect to it. Writing is blocked: the server rejects INSERT, UPDATE, DELETE and similar commands, sets timeouts and runs every query in a read-only transaction. A pgmcp-client command-line client is built alongside the server for checks from a terminal, for example `./pgmcp-client -ask "What tables do I have?" -format table`.
Who it is for. For developers and analysts who want to question their own PostgreSQL database from Cursor or Claude Desktop without writing SQL by hand.
Good fit when
- You are getting to know an unfamiliar database and want to ask which tables it has
- You need a quick answer such as "which customer placed the most orders"
- You need to find a value, for example a name, across all text columns at once with the `search` tool
- You need the result as CSV or JSON for a report, with the row count capped by the `-max-rows` flag
Not a fit when
- Your database runs on another engine: the server is built for PostgreSQL only
- You need control over every word of the query: the model writes the SQL and it may be imprecise
- The agent has to change the schema or data: the server only reads
Example request
Which customer placed the most orders? Show the top five as a table.MCP
- Transport
- http
- Authentication
- not required
Environment variables
DATABASE_URLrequired, secret- Connection string for your PostgreSQL database
OPENAI_API_KEYsecret- OpenAI key for generating SQL from a question
OPENAI_MODEL- Model used for SQL generation, gpt-4o-mini by default
AUTH_BEARERsecret- Bearer token for authorizing requests to the server
HTTP_ADDR- Server address and port, :8080 by default
HTTP_PATH- Path of the MCP endpoint, /mcp by default
Limitations
An OpenAI model turns the question into SQL. It needs an `OPENAI_API_KEY`, gpt-4o-mini runs by default, and the `OPENAI_MODEL` variable sets another model. The key is marked optional, yet the project describes no other way to get SQL from a question. The OpenAI API is not available from Russia.
The `AUTH_BEARER` variable turns on Bearer-token authorization; without it the server does not check who is calling. Set a token if other computers can reach the server.
The repository states the Apache 2.0 license, though GitHub does not recognize it.
How to disable. Remove the `pgmcp` block from the Cursor or Claude Desktop configuration and stop the `pgmcp-server` process or the container. In Kubernetes, remove the manifests deployed from the `examples/k8s` folder.
FAQ
How do I connect PGMCP to Cursor?
Start `pgmcp-server` with the `DATABASE_URL` variable, then add a pgmcp server with the http transport and the address `http://localhost:8080/mcp` to Cursor settings. A ready configuration snippet is under install methods.
What happens if the model writes wrong SQL?
The server keeps running. It returns the error, a hint to rephrase the question and the original SQL the model wrote.
Can I ask several questions at once?
Yes, the client accepts a repeated `-ask` flag: `./pgmcp-client -ask "Show tables" -ask "Count users" -format table`. The `-format` flag sets the output: table, JSON or CSV.
What does the search tool do?
It looks for a value across all text columns of the database at once. From a terminal that looks like this: `./pgmcp-client -search "john" -format table`.
How do I run PGMCP in Docker or Kubernetes?
In Docker the `ghcr.io/subnetmarco/pgmcp:latest` image with the `DATABASE_URL` variable and port 8080 is enough. For Kubernetes the `examples/k8s` folder has manifests, and the connection string goes into the `pgmcp-secret` secret.
Discussion
No questions or reviews yet.
Related
MCP serverspgEdge Postgres MCP
pgEdge Postgres MCP Server
Postgres MCP in Go with read-mode queries, EXPLAIN plans, semantic search, several databases and a ready chat client and web interface
An MCP server for PostgreSQL with several databases at once, table descriptions from the catalog, PostGIS and pgvector hints and query plans
An MCP server and skills from TigerData that help agents write PostgreSQL schemas and queries from current docs and practices
A Go MCP server and REST API for databases: PostgreSQL, MySQL, ClickHouse, Snowflake, BigQuery and more, with personal data masking and a cache
Postgres MCP (Microsoft)
Postgres MCP Server (Microsoft)
Postgres MCP from Microsoft: connection profiles with passwords in the OS keyring, Entra ID sign-in for Azure, queries, schema, CSV and server metrics
A SQLite-based SQL engine with plugins for apps, databases and files: the anyquery mcp command exposes that data to Claude, Cursor and other MCP clients
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| PGMCP (this entry) | no | not required | 540 | |
| Postgres MCP Pro | no | API key | 3,443 | index tuning, EXPLAIN plans and database health checks |
| PG-MCP Server | no | not required | 540 | several databases at once, PostGIS and pgvector hints |
| DBHub | no | not required | 3,752 | one server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite |
README in short
The repository has two sample datasets: a full marketplace schema with thousands of records and a minimal schema with a mixed-case "Categories" table for testing name case. The Go tests split into unit and integration ones, and the latter need a running PostgreSQL. The `-ldflags` build flags shrink the binaries.