PostgreSQL MCP Server

About

The PostgreSQL MCP server was the Model Context Protocol reference server for Postgres, and it is retired: the source now sits in modelcontextprotocol/servers-archived — a repository GitHub reports as archived, described as "Reference MCP servers that are no longer maintained" — and the npm package @modelcontextprotocol/server-postgres carries a deprecation notice reading "Package no longer supported." It still installs and still runs, which is why most third-party setup articles have not caught up. What it provides is deliberately small: a single tool, query, which executes read-only SQL inside a READ ONLY transaction, plus per-table schema information exposed as MCP resources at postgres://<host>/<table>/schema, with column names and data types discovered from database metadata. There is no index advice, no health check, no separate schema-listing tool, and no write mode. Install is npx @modelcontextprotocol/server-postgres with a postgres:// connection string as the argument. For active work against Postgres, the maintained alternative is Postgres MCP Pro (crystaldba/postgres-mcp), which exposes nine tools including index tuning against hypothetical indexes and a database health check, and has an explicit restricted access mode; if your database is hosted on Supabase or Neon, their platform servers add branching and logs that a raw Postgres connection cannot see. Reach for this archived server only when you want the smallest possible surface — one process, one read-only query tool, nothing else.

Installation

npx @modelcontextprotocol/server-postgres postgres://localhost/mydb

Setting up Postgres MCP Pro

1. 1.Pick an install method

   Docker is the one to default to: it needs nothing on the host, and the image rewrites localhost in your connection string to reach the host database (host.docker.internal on macOS and Windows, 172.17.0.1 on Linux) rather than looking inside the container — the failure that otherwise reads as "connection refused" against a database you can see running.

   shell

   docker pull crystaldba/postgres-mcp
   # or, on the host:
   pipx install postgres-mcp
   uv pip install postgres-mcp

2. 2.Wire it into Claude Desktop with Docker

   DATABASE_URI is passed by name in args and by value in env — that is deliberate in the project's own example, so the password is not baked into the argument list. The config file is at ~/Library/Application Support/Claude/claude_desktop_config.json on macOS and %APPDATA%/Claude/claude_desktop_config.json on Windows.

   json

   {
     "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"
         }
       }
     }
   }

3. 3.Or run it from uvx with no container

   Same flags, no Docker daemon. This is the shape to use when the database is remote anyway and the localhost remapping buys you nothing.

   json

   {
     "mcpServers": {
       "postgres": {
         "command": "uvx",
         "args": ["postgres-mcp", "--access-mode=unrestricted"],
         "env": {
           "DATABASE_URI": "postgresql://username:password@localhost:5432/dbname"
         }
       }
     }
   }

4. 4.Switch to restricted mode for anything you care about

   Replace --access-mode=unrestricted with --access-mode=restricted and every statement runs inside a read-only transaction. The parser also rejects COMMIT and ROLLBACK, which is the detail that makes it hold: without that, a model can close the read-only transaction and open a writable one, and the mode becomes decoration.

   shell

   uvx postgres-mcp --access-mode=restricted

5. 5.Install the two extensions the good tools depend on

   pg_stat_statements is what get_top_queries and analyze_workload_indexes read; hypopg is what lets explain_query cost an index that does not exist yet. Without them the server still starts and those tools simply have nothing to say — a silent degradation that looks like the server being useless.

   sql

   CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
   CREATE EXTENSION IF NOT EXISTS hypopg;

6. 6.SSE, when the client will not spawn a process

   Start it with --transport=sse and it listens on port 8000; clients point at http://localhost:8000/sse. Useful for editors that only take a URL, and for running one server against a shared dev database instead of one process per developer.

   shell

   docker run -p 8000:8000 \
     -e DATABASE_URI=postgresql://username:password@localhost:5432/dbname \
     crystaldba/postgres-mcp --access-mode=unrestricted --transport=sse

The nine tools

The first four are what the archived reference server did, roughly. The last five are the reason to switch.

What people use it for

Which one should you use?

Categories

Works With

Frequently Asked Questions

Related Guides