postgres-mcp: an MCP server for Postgres health checks, index tuning and controlled SQL execution
Postgres MCP Pro provides configurable read/write access and performance analysis for you and your AI agents.
At a glance
- What is it?
- Postgres MCP Pro wraps a Postgres connection in a Model Context Protocol server so an AI client can inspect schema, read EXPLAIN plans and run SQL under a configurable access mode. The interesting part is the access-mode switch and the index tuning surface; the risk is that you are handing an agent a database credential.
- Who is it for?
- Adopt it if you already run an MCP client and want schema-aware SQL and EXPLAIN output inside that client, and start with the read-only or restricted access mode against a staging database rather than production. Do not adopt it if you cannot give the client a dedicated low-privilege Postgres role, because the server holds whatever the connection URI grants.
- Can I use it commercially?
- Yes. MIT is a permissive licence: you can use, modify and sell software built on it, as long as you keep its copyright and licence notices.
- Is it still maintained?
- Yes. The repository last received commits 30 days ago.
- What is it written in?
- Mainly Python, according to GitHub's language statistics.
Answers come from the project's GitHub data, last synced on September 15, 2026, and from our analysis. They are not legal advice.
DEEP OPEN-SOURCE ANALYSIS
The gap postgres-mcp fills between an AI client and a live Postgres instance
An AI coding assistant that has never seen your schema will guess at column names, invent indexes that already exist, and write joins that ignore your actual foreign keys. postgres-mcp is a Model Context Protocol server, so it plugs into clients that already speak MCP, and it exposes the database rather than a file tree. The README frames the scope as the whole development process, from initial coding through testing and deployment to production tuning. That is a broad claim, and the feature list behind it is specific: database health analysis, index tuning, query plan review, schema intelligence and safe SQL execution. The target user is someone who already has an MCP-capable client and a Postgres instance, and who wants the assistant to reason about real tables instead of a pasted schema dump. It is not a migration tool, not an ORM, and not a replacement for psql.
What the server actually exposes: health checks, index tuning, EXPLAIN and schema context
The README lists five capability groups. Database health covers index health, connection utilization, buffer cache, vacuum health, sequence limits and replication lag. Index tuning is described as exploring thousands of possible indexes to find the best solution for a workload, using what the README calls industrial-strength algorithms. Query plans are handled by reviewing EXPLAIN plans and simulating the impact of hypothetical indexes. Schema intelligence means SQL generation informed by a detailed understanding of the schema. Safe SQL execution is the configurable access control layer, including a read-only mode and safe SQL parsing. Those last two are the ones that decide whether this is usable outside a laptop. A read-only mode plus a parser that inspects statements before they reach the server is a different proposition from a client that simply executes whatever string the model produced. The README does not enumerate the tool names or the exact JSON schema of each MCP tool, so if you need the precise call signatures you will have to read the MCP API section of the repository rather than the overview.
Two transports, one configuration file, and the localhost remapping detail
The server supports stdio and Server-Sent Events transports. stdio is what the Claude Desktop examples use, and it is the simpler of the two because the client spawns the process. Configuration lives in the client, not in the server. On macOS that file is ~/Library/Application Support/Claude/claude_desktop_config.json; on Windows it is %APPDATA%/Claude/claude_desktop_config.json. You add an entry under mcpServers. With Docker the command is docker with args run -i --rm -e DATABASE_URI crystaldba/postgres-mcp --access-mode=unrestricted, and the connection string goes in an env block as DATABASE_URI. With uvx the command is uvx and the args are just postgres-mcp --access-mode=unrestricted. There are equivalent blocks for pipx and for uv run. One detail worth reading twice: the Docker image remaps the hostname localhost so it resolves from inside the container, using host.docker.internal on macOS and Windows and 172.17.0.1 or the appropriate host address on Linux. If you run the server outside Docker and point it at localhost, that remapping does not apply, and the two setups are not interchangeable when you copy a config between machines.
Installation paths and why the README leans toward Docker
Prerequisites are database credentials plus either Docker or Python 3.12 or higher. The README suggests confirming credentials with psql or a GUI tool such as pgAdmin before wiring anything up, which is sensible because a failing MCP server surfaces as a client-side error rather than a clear connection message. For Docker, the single command is docker pull crystaldba/postgres-mcp. For Python, pipx install postgres-mcp if pipx is present, otherwise uv pip install postgres-mcp, with a link to the uv installation instructions for anyone who does not have uv yet. The README states a preference: Docker is generally recommended because Python users can encounter more environment-specific issues, while also conceding that it often makes sense to use whichever method you are most familiar with. That is a fair read of the trade-off. A container pins the dependency set; a pipx or uvx install tracks whatever the resolver picks at install time and depends on your Python version being 3.12 or newer.
The access-mode flag is the whole security story, and it is a single string
Every configuration example in the README passes --access-mode=unrestricted. That is the value shown for Docker, uvx, pipx and uv alike. The README also states that the server supports read-only mode and safe SQL parsing, and describes the access control as configurable, so a more restrictive value clearly exists. What the supplied material does not give is the list of valid values beyond unrestricted, or how the parser classifies a statement as safe. That is the gap to close before pointing this at anything you care about. The practical consequence is straightforward: the server can do whatever the role in your DATABASE_URI can do, minus whatever the access mode and parser block. If that URI carries a superuser or a role with DDL rights, the access mode is the only thing standing between a model-generated statement and your schema. Use a dedicated role. The README's own examples are written for a local database at localhost:5432, which is consistent with the intended starting point being a development instance.
Where postgres-mcp is the wrong tool, and what to compare it against
The obvious alternative is a plain database client plus the psql or pgAdmin workflow the README already assumes you have for checking credentials. The difference in approach is that psql executes exactly what you type and returns raw output, while postgres-mcp puts a model between your intent and the statement, adds schema context automatically, and can propose index changes you did not ask for. If your task is a one-off query, a migration you have already written, or anything where you want to read the exact SQL before it runs, psql is faster and has no ambiguity about what executed. A second alternative is any MCP server that exposes a database connection without the tuning and health layers; those are thinner, and the trade-off is that you get less schema reasoning in exchange for a smaller surface to audit. postgres-mcp is also the wrong choice when the database is not reachable from where the client runs, when your organisation forbids sending schema metadata to a third-party model provider, or when the Postgres version is old enough that the health checks and hypothetical index simulation return nothing useful. The README does not state a minimum supported Postgres version, which is itself a reason to test against your specific instance before committing.
Maintenance cost, release cadence and the MIT licence
The repository is MIT licensed, which permits commercial use and modification provided the copyright notice and permission notice are retained. That is a permissive licence and it places no copyleft obligation on your own code, but it also means the project offers no warranty, and nothing in the licence obliges anyone to fix a bug you report. The release history supplied shows v0.2.0 in April 2025, v0.2.1 a day later, and v0.3.0 in May 2025, with the repository's last push dated August 2026. The version numbers are still in the 0.x range, so expect the configuration surface, the access-mode semantics and the MCP tool names to change between releases. For an operator, that means pinning a version rather than tracking latest, and re-reading the access-mode documentation after every upgrade, because a change in what a mode permits is a security change even when the release notes describe it as a feature. This is not legal advice; if you are deploying inside a regulated environment, have someone review the licence text and your own data-handling obligations.
Editorial conclusion
Adopt it if you already run an MCP client and want schema-aware SQL and EXPLAIN output inside that client, and start with the read-only or restricted access mode against a staging database rather than production. Do not adopt it if you cannot give the client a dedicated low-privilege Postgres role, because the server holds whatever the connection URI grants. Before trusting it, verify what --access-mode=unrestricted actually permits in your client, confirm which DDL and DML statements your role can execute, and check whether the index tuning output is advisory only or comes with a script you would have to apply yourself.
Community notes