postgres-mcp

Multi-DB Postgres MCP Server für Cursor / andere MCP-Clients.
Unterstützt Schema-Exploration, sicheres SQL, EXPLAIN, Health-Checks und Index-Empfehlungen.

Voraussetzungen

• Node.js 22+
• Postgres-Zugang (Connection-URI)
• Optional: Docker

Empfohlene Postgres-Extensions (für Slow-Queries / Index-Tuning):

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

pg_stat_statements muss zusätzlich in shared_preload_libraries aktiv sein und Postgres neu gestartet werden.

Schnellstart (lokal)

npm install
npm run build

Eine DB:

DATABASE_URL='postgresql://user:pass@host:5432/dbname' \
ACCESS_MODE=restricted \
npm start

Mehrere DBs:

DB_STAGING_URL='postgresql://user:pass@host:5432/staging' \
DB_PROD_URL='postgresql://user:pass@host:5432/prod' \
DEFAULT_DB=staging \
ACCESS_MODE=restricted \
npm start

HTTP-Transport (für Docker / Remote):

npm run start:http
# -> http://0.0.0.0:8000/mcp
# Health: http://0.0.0.0:8000/health

Konfiguration

Datenbanken

Variable	Beschreibung
DATABASE_URL	Einzelne DB (Alias default)
DB_<NAME>_URL	Multi-DB, z. B. DB_STAGING_URL, DB_PROD_URL
DATABASES	Alternativ: staging|url,prod|url oder JSON {"staging":"url"}
DEFAULT_DB	Default-Alias, wenn mehrere DBs konfiguriert sind

Tools akzeptieren optional db (Alias aus list_databases). Ohne Angabe wird DEFAULT_DB verwendet.

Access Mode

Wert	Bedeutung
unrestricted	Read/Write (Default, für Dev)
restricted	Read-only, 30s Statement-Timeout, kein COMMIT/ROLLBACK

Setzen über Env oder CLI:

ACCESS_MODE=restricted
# oder
node dist/index.js --access-mode=restricted

Transport

Variable / Flag	Default	Beschreibung
TRANSPORT / --transport=	stdio	stdio oder http
BIND_HOST / --host=	0.0.0.0	HTTP Bind-Adresse (nicht HOST — Coolify/PaaS überschreibt das)
PORT / --port=	8000	HTTP Port

Cursor einbinden

Stdio (lokal)

In Cursor MCP Settings / mcp.json:

{
  "mcpServers": {
    "postgres": {
      "command": "node",
      "args": [
        "/ABSOLUTER/PFAD/postgres-mcp/dist/index.js",
        "--access-mode=restricted"
      ],
      "env": {
        "DB_STAGING_URL": "postgresql://user:pass@host:5432/staging",
        "DB_PROD_URL": "postgresql://user:pass@host:5432/prod",
        "DEFAULT_DB": "staging"
      }
    }
  }
}

Vorher einmal npm run build ausführen.

HTTP (Docker / Remote)

{
  "mcpServers": {
    "postgres": {
      "url": "http://localhost:8000/mcp"
    }
  }
}

Docker

Build:

docker build -t postgres-mcp .

Run:

docker run --rm -p 8000:8000 \
  -e ACCESS_MODE=restricted \
  -e DEFAULT_DB=staging \
  -e DB_STAGING_URL='postgresql://user:pass@host:5432/staging' \
  -e DB_PROD_URL='postgresql://user:pass@host:5432/prod' \
  postgres-mcp

Endpoints:

• MCP: http://localhost:8000/mcp
• Health: http://localhost:8000/health

Hinweis: Wenn Postgres auf dem Host läuft, localhost in der URI je nach OS durch host.docker.internal ersetzen.

Tools

Tool	Zweck
list_databases	Konfigurierte DB-Aliase anzeigen
list_schemas	Schemas listen
list_objects	Tables / Views / Sequences / Extensions
get_object_details	Spalten + Indexes eines Objekts
execute_sql	SQL ausführen (max. 50 Rows default)
explain_query	EXPLAIN / EXPLAIN ANALYZE / hypopg
get_top_queries	Slow Queries (pg_stat_statements)
analyze_workload_indexes	Index-Empfehlungen aus Workload
analyze_query_indexes	Index-Empfehlungen für konkrete Queries
analyze_db_health	Health: index, connection, vacuum, sequence, replication, buffer, constraint, all

Typischer KI-Flow:

1. list_databases
2. list_schemas / list_objects
3. get_object_details
4. execute_sql mit db: "staging"

Tests

Read-only Integrationstests gegen eine echte DB:

export TEST_DATABASE_URL='postgresql://user:pass@host:5432/dbname'
npm test

Die Tests laufen im restricted-Mode und prüfen alle Tools inkl. Multi-DB und Error-Cases.

Vorlage: .env.test.example

Entwicklung

npm install
npm run build
npm start
npm run start:http
npm test

Build-Output liegt in dist/.