writenotenow/postgres-mcp repository overview

⁠postgres-mcp

PostgreSQL MCP Server binding the Model Context Protocol to a secure PostgreSQL sandbox.

Features Code Mode — a revolutionary approach that provides access to all 248 tools through a secure, true V8 isolate (worker_threads), eliminating the massive token overhead of multi-step tool calls. Also includes schema introspection, migration tracking, smart tool filtering, deterministic error handling, connection pooling, HTTP/SSE transport, OAuth 2.1 authentication, and support for citext, ltree, pgcrypto, pg_cron, pg_stat_kcache, pgvector, PostGIS, and HypoPG.

248 Specialized Tools · 23 Resources · 20 AI-Powered Prompts

GitHub⁠ • npm Package⁠ • MCP Registry⁠ • Wiki⁠ • Tool Reference⁠ • Changelog⁠

⁠🎯 What Sets Us Apart

⁠Suggested Rule (Add to AGENTS.md, GEMINI.md, etc)

MCP TOKEN MANAGEMENT:

• Token Visibility: When interacting with postgres-mcp, always monitor the _meta.tokenEstimate (or metrics.tokenEstimate in Code Mode) returned in tool responses.
• Audit Resource: Use the postgres://audit resource to review session-level token consumption and identify high-cost operations.
• Proactive Efficiency: If operations are consuming high token counts, prefer code mode and proactively use limit parameters.

⁠Extension Support

⁠MCP Resources (23)

Real-time database meta-awareness - AI accesses these automatically:

Full resources list →⁠

⁠MCP Prompts (20)

Guided workflows for complex operations:

Full prompts list →⁠

⁠🚀 Quick Start (2 Minutes)

⁠1. Pull the Image

docker pull writenotenow/postgres-mcp:latest

⁠2. Add to MCP Config

Add this to your MCP client config (e.g., ~/.cursor/mcp.json for Cursor):

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "--rm",
        "-i",
        "-e",
        "POSTGRES_HOST",
        "-e",
        "POSTGRES_PORT",
        "-e",
        "POSTGRES_USER",
        "-e",
        "POSTGRES_PASSWORD",
        "-e",
        "POSTGRES_DATABASE",
        "writenotenow/postgres-mcp:latest",
        "--tool-filter",
        "codemode",
        "--audit-log",
        "/tmp/postgres-logs/audit.jsonl"
      ],
      "env": {
        "POSTGRES_HOST": "host.docker.internal",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DATABASE": "your_database"
      }
    }
  }
}

⁠🔧 Configuration

⁠Environment Variables

PostgreSQL Connection (required):

-e POSTGRES_HOST=localhost
-e POSTGRES_PORT=5432
-e POSTGRES_USER=your_user
-e POSTGRES_PASSWORD=your_password
-e POSTGRES_DATABASE=your_database

Or use a connection string:

-e POSTGRES_URL=postgres://user:pass@host:5432/database

Server & Tuning:

⁠🔗 Database Connection Scenarios

⁠🛠️ Tool Filtering

• Requires admin OAuth scope — execution is logged for audit

📖 See Full Installation Guide →⁠

⁠What Can You Filter?

The --tool-filter argument accepts groups or tool names — mix and match freely:

⁠Tool Groups (22 Available)

⁠Syntax Reference

⁠🌐 HTTP/SSE Transport (Remote Access)

For remote access, web-based clients, or HTTP-compatible MCP hosts:

docker run --rm -p 3000:3000 \
  -e POSTGRES_URL=postgres://user:pass@host:5432/db \
  writenotenow/postgres-mcp:latest \
  --transport http --port 3000

With simple bearer token authentication:

docker run --rm -p 3000:3000 \
  -e POSTGRES_URL=postgres://user:pass@host:5432/db \
  -e MCP_AUTH_TOKEN=my-secret-token \
  writenotenow/postgres-mcp:latest \
  --transport http --port 3000

With OAuth 2.1 (recommended for production):

docker run --rm -p 3000:3000 \
  -e POSTGRES_URL=postgres://user:pass@host:5432/db \
  -e OAUTH_ENABLED=true \
  -e OAUTH_ISSUER=http://keycloak:8080/realms/postgres-mcp \
  -e OAUTH_AUDIENCE=postgres-mcp-client \
  writenotenow/postgres-mcp:latest \
  --transport http --port 3000

Stateless mode (serverless, no sessions):

docker run --rm -p 3000:3000 \
  -e POSTGRES_URL=postgres://user:pass@host:5432/db \
  writenotenow/postgres-mcp:latest \
  --transport http --port 3000 --stateless

The server supports two MCP transport protocols simultaneously, enabling both modern and legacy clients to connect:

⁠Streamable HTTP (Recommended)

Modern protocol (MCP 2025-03-26) — single endpoint, session-based:

Sessions are managed via the Mcp-Session-Id header.

Docker Health Check: Built-in HEALTHCHECK is transport-aware and validates database and HTTP endpoint connectivity.

⁠🛡️ Supply Chain Security

For reproducible builds, use SHA-pinned images:

docker pull writenotenow/postgres-mcp@sha256:<manifest-digest>

Find SHA tags here⁠

⁠📄 License

MIT License - See LICENSE⁠