postgres-mcp: A PostgreSQL MCP Server for AI Coding Assistants

What postgres-mcp Solves and Who It Is For

Database performance work during AI-assisted development usually hits a wall: the AI agent can suggest SQL and ORM code, but it cannot actually look at query plans, check index health, or inspect live schema details. postgres-mcp (PyPI: `postgres-mcp`, also available as `crystaldba/postgres-mcp` on Docker Hub) closes that gap by implementing the Model Context Protocol, which lets MCP-capable editors and AI clients call the server's tools as structured functions.

The primary audience is developers using AI coding assistants who already run PostgreSQL and want the assistant to do real database work in the same session as code edits. The README describes a concrete use case: an AI-generated movie app with painfully slow SQLAlchemy ORM queries. Using postgres-mcp with Cursor, the team identified and fixed ORM query patterns, added missing indexes, and repaired a broken page by letting the agent explore the data directly.

This is not a database GUI and it is not a standalone monitoring dashboard. Its value is in connecting an AI agent's reasoning loop to live database state.

Architecture and the Five Core Capabilities

postgres-mcp runs as a server process that speaks the Model Context Protocol over either stdio (for local editor integrations) or Server-Sent Events (SSE, for networked clients). The client (Claude Desktop, Cursor, or any MCP-compatible tool) invokes the server's tools as structured function calls; the server executes them against PostgreSQL through the `psycopg` connection pool.

The five main capability areas are:

1. Database health checks: index health, connection utilization, buffer cache hit rates, vacuum health, sequence limits, and replication lag. These run as read queries against system views.

2. Index tuning: the README describes it as exploring "thousands of possible indexes" using "industrial-strength algorithms" to find the best solution for a given workload. The underlying dependency is `pglast` (version 7.11 is pinned), a PostgreSQL SQL parser used to analyze query structure.

3. Query plan analysis: validate performance by reviewing EXPLAIN output and simulate the impact of hypothetical indexes before creating them.

4. Schema intelligence: the server maintains a detailed model of the database schema to guide context-aware SQL generation by the AI.

5. Safe SQL execution: access modes (described below) control what the agent can actually do. SQL is parsed with `pglast` before execution to enforce access restrictions.

The dependency set in `pyproject.toml` is intentionally narrow: `mcp[cli]`, `psycopg[binary]`, `humanize`, `pglast`, `attrs`, `psycopg-pool`, and `instructor`. Python 3.12 or higher is required.

Installing postgres-mcp and Connecting to Claude Desktop

The README recommends Docker as the most reliable installation method because Python users can encounter environment-specific issues.

To pull the Docker image:

docker pull crystaldba/postgres-mcp

If you prefer Python, install with `pipx`:

pipx install postgres-mcp

Or with `uv`:

uv pip install postgres-mcp

Once installed, add an entry to your MCP client's configuration. For Claude Desktop on macOS, the config lives at `~/Library/Application Support/Claude/claude_desktop_config.json`. The Docker entry (with `--access-mode=unrestricted` for a development database) looks like this:

{
  "mcpServers": {
    "postgres": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URI",
        "crystaldba/postgres-mcp",
        "--access-mode=unrestricted"
      ],
      "env": {
        "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
      }
    }
  }
}

The Docker image automatically remaps `localhost` to `host.docker.internal` on macOS/Windows and to `172.17.0.1` on Linux, so you can point the connection URI at your local Postgres without extra network configuration.

After saving the config and restarting Claude Desktop, the postgres tools appear in the tool list. Ask the assistant to run a health check or examine a slow query, and it will call the server's tools using the live connection.

Access Modes: Choosing Between Unrestricted and Restricted

The README documents two access modes selected with the `--access-mode` flag:

`--access-mode=unrestricted` allows full read/write access: schema changes, data modifications, index creation. The README says this is suitable for development environments.

`--access-mode=restricted` limits operations to read-only transactions. The README recommends this for production environments, and it is the safer default when you are connecting to a database with real data.

This is a meaningful design choice: many MCP database servers offer no access control at all and rely on the database user's grants. postgres-mcp adds a second layer by parsing SQL at the application level before executing it. The trade-off is that `pglast`'s parsing must handle every SQL variant your agent generates; unusual or vendor-specific syntax could be rejected or incorrectly classified.

For a production read replica, `restricted` mode is straightforward. For a primary used for schema migrations during development, `unrestricted` makes sense. There is no row-level or table-level restriction between these two options. If you need finer-grained control, database-level grants on the Postgres user are a better tool.

Transport Options: stdio vs. SSE

postgres-mcp supports two MCP transport modes. The stdio transport is the standard choice for local integrations with desktop editors. The editor process launches the server as a child process and communicates over standard streams. This is what all four configuration examples in the README use (Docker, uvx, pipx, and uv).

The SSE (Server-Sent Events) transport is for networked scenarios where the server runs on a separate host and the client connects over HTTP. The README mentions SSE as a supported option for "flexibility in different environments". For a team that wants a single postgres-mcp server process shared by multiple developers, or a server running in a remote environment, SSE is the path. The README does not document the exact flag for starting in SSE mode; that configuration detail is in the MCP documentation linked from the README.

For most local development setups with Claude Desktop or Cursor, stdio with Docker or a Python package is sufficient.

Limitations and Cases Where It Is the Wrong Tool

postgres-mcp targets PostgreSQL exclusively. There is no support for MySQL, SQLite, or other databases, and adding support would require separate development since the tool uses PostgreSQL-specific system views and `pglast`'s Postgres SQL parser.

The index tuning capability depends on the AI agent formulating the right queries to analyze. The server provides the analysis tools, but the agent must know to invoke them. An agent that does not call the index-check tools will produce no index recommendations. The quality of analysis depends on both the server's tooling and the AI client's prompting.

The `pglast` dependency is pinned at version 7.11. If `pglast` cannot parse a SQL statement (vendor extension, unusual syntax, or a statement type it does not handle), the safe-SQL parsing step may reject it or pass it through without proper classification. The behavior in these edge cases is not documented in the README.

Postgres MCP Pro is not a replacement for dedicated database monitoring tools like pganalyze or Datadog's PostgreSQL integration. Those tools continuously collect metrics and provide alerting, while postgres-mcp operates on-demand at the request of an AI agent. Running health checks from an agent during a coding session is useful for diagnosis; it is not a substitute for continuous monitoring.

An alternative approach is pg_query_settings (a PgBouncer or pgBadger-based workflow) or using psql directly in a shell tool. The difference is that postgres-mcp exposes structured, AI-callable functions rather than raw terminal access, which allows the AI agent to act on results programmatically rather than parsing text output.

Release History and License

The project has three published releases: v0.2.0 on 2025-04-16, v0.2.1 on 2025-04-17, and v0.3.0 on 2025-05-16. The last push to the repository was on 2026-08-17. The project is MIT-licensed.

The package name on PyPI is `postgres-mcp` and the command-line entry point installed by `pyproject.toml` is also `postgres-mcp`. The Docker image is at `crystaldba/postgres-mcp`. There is a Discord server linked from the README (`discord.gg/4BEHC7ZM`) for community support.

The Python requirement of 3.12 or higher is a real constraint: users on older Python installations will need to use Docker. The `uv` installer is the recommended path if you prefer Python but do not have pipx; the README links to the uv installation instructions at `docs.astral.sh/uv/getting-started/installation/`.

Editorial conclusion

postgres-mcp is a good fit for engineers who already use an MCP-capable AI assistant (Claude, Cursor, or compatible clients) and want that assistant to reach into a real PostgreSQL database to diagnose slow queries, propose indexes, or inspect schema. The critical thing to verify before wiring it to a production database is the access mode: use `--access-mode=restricted` to limit the agent to read-only transactions. Teams who want a standalone database GUI, a query editor unrelated to AI, or support for databases other than PostgreSQL should look elsewhere. The project is MIT-licensed with the last push on 2026-08-17.

Frequently asked questions

Official sources

1. crystaldba/postgres-mcp on GitHub
2. Issues
3. License: MIT
4. README
5. Releases