PG-MCP Server
An MCP server for PostgreSQL with several databases at once, table descriptions from the catalog, PostGIS and pgvector hints and query plans
- 540 ★ on the repository
- Last commit
- MIT
Extended access
Why this level
- Connects to PostgreSQL databases with a login and password string that the agent passes in the conversation
- Reads tables and data samples and writes query text to a DEBUG-level log
- Listens on port 8000 on all network interfaces with no access check
Install
- Works in
Manual install
docker-compose up -dRun it inside the cloned `https://github.com/stuzero/pg-mcp-server.git` repository; the server listens on port 8000.
Access and checks
How we reviewExtended accessThe tool runs code or makes network calls and only reads external data.
- Connects to PostgreSQL databases with a login and password string that the agent passes in the conversation
- Reads tables and data samples and writes query text to a DEBUG-level log
- Listens on port 8000 on all network interfaces with no access check
This is third-party code. Review the repository files before installing.
What it does
The Python server starts as an HTTP application with SSE transport on port 8000 and serves several PostgreSQL databases at once. The agent calls the `connect` tool with a connection string and gets back a connection ID, `conn_id`. All later queries use that ID, and `disconnect` closes the pool. Two tools run queries. `pg_query` turns on a read-only transaction before each query and returns rows as a list of dictionaries, while `pg_explain` wraps the query in `EXPLAIN (FORMAT JSON)` and returns the full plan. The agent reads the schema through resources addressed like `pgmcp://{conn_id}/schemas`: schemas, tables with row counts and descriptions from the database catalog, columns, constraints, indexes, extensions and paged data samples. For the PostGIS and pgvector extensions, the `server/resources/extensions` folder holds YAML references with types, functions and examples, and new ones are added as separate files. Four ready prompts (`generate_sql`, `validate_nl`, `justify_sql` and `generate_vega`) lead the agent from a plain-language question to SQL and a Vega-Lite chart spec.
Who it is for. For developers and analysts who work with PostgreSQL, keep several databases and want an agent to study the schema itself and write read-only queries.
Good fit when
- You have several working databases and the agent has to switch between them in one session without restarting the server
- The schema is poorly documented and the agent needs the table and column descriptions already stored in the PostgreSQL catalog
- The database has PostGIS or pgvector and the agent must know their types and functions before writing a query
- You want to turn a plain-language question into SQL and get a Vega-Lite chart spec right away
Not a fit when
- You want a command in the client config with no separate server: here the server waits for HTTP connections and is started in advance
- You need index tuning and database health checks: the postgres-mcp entry covers that role
- Your Python is older than 3.13 and you have no Docker: the project requires version 3.13 or newer
- You need a tool for MySQL, SQL Server or SQLite: the server works only with PostgreSQL
- You need to change data or schema: queries run in a read-only transaction
Example request
Connect to the sales database, find the orders tables and show the five customers with the biggest purchases, then explain the plan of that queryMCP
- Transport
- sse
- Authentication
- not required
Environment variables
LOG_LEVEL- Server log level, DEBUG by default
PG_MCP_URL- SSE address for the demo clients, for example `http://localhost:8000/sse`
Limitations
The project is at version 0.1.0, and the repository's last change dates from September 10, 2025. MIT License.
The agent passes the connection string through the `connect` tool, so the database login and password go through the conversation with the model instead of sitting in the client config. The server keeps the mapping of IDs to connection strings in process memory.
The default log level is DEBUG, `docker-compose.yml` sets it to DEBUG too, and the text of every query is written to the log with its connection ID.
Write protection rests on the `SET TRANSACTION READ ONLY` command: back it up with the database account's rights.
Port 8000 listens on all network interfaces (`0.0.0.0`), and the server has no access check of its own. The `server` folder from `docker-compose.yml` is mounted into the container for development with code reloading.
How to disable. Stop the container with `docker-compose down` or end the `python -m server.app` process, then remove the server address from the client settings. If connections were open, call `disconnect` for each ID.
FAQ
How do I start the server?
Clone the repository and run `docker-compose up -d`: the container opens port 8000. Without Docker, run `uv sync`, activate the `.venv` environment and start `python -m server.app`. Python 3.13 or newer is required.
Which address should the client use?
The repository example uses `http://localhost:8000/sse`: that address is set in the `PG_MCP_URL` variable for the demo clients.
What does connect return and why is conn_id needed?
The tool registers the connection string and returns an opaque ID. Resource addresses and queries use the ID instead of the string, so the login and password do not show up in `pgmcp://` addresses.
Can the server work with several databases at once?
Yes. Each `connect` call creates a separate connection with its own ID, and the agent picks the database by passing the right `conn_id`.
How can I test the server without my own agent?
The `test.py` script takes a connection string as an argument. For plain-language queries there is `example-clients/claude_cli.py`, which reads `ANTHROPIC_API_KEY`, `DATABASE_URL` and `PG_MCP_URL` from the `.env` file.
Which other demo clients are there?
Besides the Claude client, the `example-clients` folder has `gemini-agent-cli.py` and `ollama_cli.py` for running with Gemini and local Ollama models.
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 and skills from TigerData that help agents write PostgreSQL schemas and queries from current docs and practices
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 Go MCP server and REST API for databases: PostgreSQL, MySQL, ClickHouse, Snowflake, BigQuery and more, with personal data masking and a cache
A Python MCP server for MySQL: listing tables, reading data, running SQL and inspecting schema through a controlled interface
Google's open-source MCP server for databases: ready tools for Postgres, MySQL, BigQuery, Spanner and more, plus custom tools in tools.yaml
Comparison with similar tools
Entries that share the main search query, and how they differ.
| Entry | Official | Authentication | Repository stars | Main difference |
|---|---|---|---|---|
| PG-MCP Server (this entry) | no | not required | 540 | |
| Postgres MCP Pro | no | API key | 3,418 | a server with index tuning, database health checks and launch through uvx or Docker |
| DBHub | no | not required | 3,703 | one server for PostgreSQL, MySQL, MariaDB, SQL Server and SQLite with a read-only mode and an SSH tunnel |
| pgEdge Postgres MCP | no | not required | 239 | postgres MCP in Go with read-mode queries |
README in short
The repository explains how the server extends the reference PostgreSQL implementation for MCP: SSE transport, several databases, catalog descriptions, extension references, query plan analysis and connection management. It gives ways to run through Docker Compose and by hand, a sample agent prompt and a list of resource addresses. Alongside are demo clients for Claude, Gemini and Ollama, the `test.py` script, a `.env.example` template and the `server`, `prompts` and `resources` source folders.