Quick Start

Quick Start

Get postgres-mcp running in under 5 minutes.

---

Prerequisites

• Node.js 24+ (LTS recommended)
• PostgreSQL 12-18 (tested with PostgreSQL 18.1)
• npm or yarn

---

Installation Options

Option 1: From Source (Recommended for Development)

git clone https://github.com/neverinfamous/postgres-mcp.git
cd postgres-mcp
npm install
npm run build

Run the server:

node dist/cli.js --transport stdio --postgres postgres://user:password@localhost:5432/database

Option 2: npm Global Install

npm install -g @neverinfamous/postgres-mcp

Option 3: Docker

docker pull writenotenow/postgres-mcp:latest

---

MCP Client Configuration

Cursor IDE / Claude Desktop

Add to your MCP configuration file (~/.cursor/mcp.json or equivalent):

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "node",
      "args": [
        "C:/path/to/postgres-mcp/dist/cli.js",
        "--tool-filter",
        "codemode"
      ],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "your_username",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_DATABASE": "your_database"
      }
    }
  }
}

Note: Code Mode provides access to all 248 tools via a secure sandbox. See Tool-Filtering for other options.

Docker Configuration

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

Docker Note: Use host.docker.internal to connect to PostgreSQL running on your host machine.

---

Connection String Formats

Direct Connection String

--postgres postgres://user:password@localhost:5432/database

Environment Variables

Variable	Description
POSTGRES_HOST	Database hostname
POSTGRES_PORT	Database port (default: 5432)
POSTGRES_USER	Username
POSTGRES_PASSWORD	Password
POSTGRES_DATABASE	Database name
POSTGRES_URL	Full connection URL (alternative)

---

Common Connection Scenarios

Scenario	Host to Use	Example
PostgreSQL on host machine	localhost	postgres://user:pass@localhost:5432/db
PostgreSQL in Docker	Container name	postgres://user:pass@postgres-container:5432/db
From Docker to host	host.docker.internal	postgres://user:pass@host.docker.internal:5432/db

Cloud Providers

Provider	Example Hostname
AWS RDS	your-instance.xxxx.us-east-1.rds.amazonaws.com
Google Cloud SQL	project:region:instance (via Cloud SQL Proxy)
Azure PostgreSQL	your-server.postgres.database.azure.com
Supabase	db.xxxx.supabase.co
Neon	ep-xxx.us-east-1.aws.neon.tech

---

Verify Installation

Test from command line:

# Show server info
node dist/cli.js info

# List available tools
node dist/cli.js list-tools

---

Next Steps

• Tool-Filtering - Configure tool presets for your IDE
• HTTP-Transport - Remote access via Streamable HTTP or legacy SSE
• Code-Mode - Enable 70-90% token reduction
• Extension-Overview - Explore pgvector, PostGIS, and more
• Home - Explore introspection and migration tools for schema analysis and migration tracking