Skip to content

MCP Configuration

Jump to bottom
Temp edited this page Oct 8, 2025 · 2 revisions

MCP Configuration

Configure PostgreSQL MCP Server with Claude Desktop, Cursor, and other MCP clients.

📋 Prerequisites

  1. PostgreSQL Database (version 13-18)
  2. MCP Client (Claude Desktop, Cursor, etc.)
  3. Environment Variable: DATABASE_URI

🔧 Configuration by Client

Claude Desktop

Edit your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI=postgresql://username:password@host:5432/database",
        "neverinfamous/postgres-mcp:latest",
        "--access-mode=restricted"
      ]
    }
  }
}

Using Python installation:

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "postgres-mcp",
      "args": ["--access-mode=restricted"],
      "env": {
        "DATABASE_URI": "postgresql://username:password@host:5432/database"
      }
    }
  }
}

Cursor IDE

Add to your Cursor settings:

File: Settings → Features → Model Context Protocol

{
  "mcpServers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run",
        "-i",
        "--rm",
        "-e",
        "DATABASE_URI=postgresql://username:password@host:5432/database",
        "neverinfamous/postgres-mcp:latest",
        "--access-mode=restricted"
      ]
    }
  }
}

Generic MCP Client

For any MCP-compatible client:

{
  "servers": {
    "postgres-mcp": {
      "command": "docker",
      "args": [
        "run", "-i", "--rm",
        "-e", "DATABASE_URI=postgresql://user:pass@host:5432/db",
        "neverinfamous/postgres-mcp:latest"
      ]
    }
  }
}

🔒 Security Modes

Restricted Mode (Production)

Recommended for production databases.

{
  "args": [
    "docker", "run", "-i", "--rm",
    "-e", "DATABASE_URI=...",
    "neverinfamous/postgres-mcp:latest",
    "--access-mode=restricted"
  ]
}

Features:

  • ✅ Read-only operations
  • ✅ Advanced SQL validation
  • ✅ Query timeout protection
  • ✅ Parameter binding required

Unrestricted Mode (Development)

Use only in development/testing environments.

{
  "args": [
    "docker", "run", "-i", "--rm",
    "-e", "DATABASE_URI=...",
    "neverinfamous/postgres-mcp:latest",
    "--access-mode=unrestricted"
  ]
}

Features:

  • ⚠️ Full read/write access
  • ✅ Parameter binding protection
  • ⚠️ DDL operations allowed
  • ⚠️ Use with caution

🌍 Environment Variables

DATABASE_URI (Required)

PostgreSQL connection string format:

postgresql://username:password@hostname:port/database?options

Examples:

# Local database
export DATABASE_URI="postgresql://postgres:password@localhost:5432/mydb"

# Remote database with SSL
export DATABASE_URI="postgresql://user:pass@db.example.com:5432/prod?sslmode=require"

# Cloud database (AWS RDS)
export DATABASE_URI="postgresql://admin:pass@mydb.region.rds.amazonaws.com:5432/database"

# With connection pooling
export DATABASE_URI="postgresql://user:pass@localhost:5432/db?pool_size=20"

Connection Options:

  • sslmode=require - Require SSL/TLS
  • connect_timeout=10 - Connection timeout (seconds)
  • application_name=myapp - Application identifier
  • pool_size=20 - Connection pool size

📝 Connection String Components

postgresql://username:password@hostname:port/database?options
           │         │         │        │    │        │
           │         │         │        │    │        └─ Optional parameters
           │         │         │        │    └─ Database name
           │         │         │        └─ Port (default: 5432)
           │         │         └─ Hostname or IP
           │         └─ Password
           └─ Username

🧪 Testing Your Configuration

Step 1: Verify Connection

Start your MCP client and try:

list_schemas()

Expected: List of database schemas

Step 2: Check Extensions

get_top_queries(sort_by="total_time", limit=5)

Expected: Query statistics (requires pg_stat_statements)

Step 3: Test Security Mode

In Restricted Mode, this should fail:

execute_sql(sql="DROP TABLE test")

Expected error: "Operation not allowed in restricted mode"

🐳 Docker Configuration

Docker Run with Environment File

Create .env file:

DATABASE_URI=postgresql://user:pass@host:5432/db
ACCESS_MODE=restricted

Run with env file:

docker run -i --rm --env-file .env neverinfamous/postgres-mcp:latest

Docker Compose

Create docker-compose.yml:

version: '3.8'
services:
  postgres-mcp:
    image: neverinfamous/postgres-mcp:latest
    stdin_open: true
    environment:
      - DATABASE_URI=postgresql://user:pass@postgres:5432/db
    command: ["--access-mode=restricted"]
    depends_on:
      - postgres

  postgres:
    image: postgres:16
    environment:
      - POSTGRES_PASSWORD=password
      - POSTGRES_DB=mydb
    volumes:
      - pgdata:/var/lib/postgresql/data

volumes:
  pgdata:

🔍 Troubleshooting

"Connection Refused"

# Check PostgreSQL is running
pg_isready -h localhost -p 5432

# Verify firewall rules
telnet hostname 5432

"Authentication Failed"

# Test connection manually
psql "postgresql://user:pass@host:5432/db"

# Check pg_hba.conf for access rules

"Extension Not Found"

-- Install required extensions
CREATE EXTENSION IF NOT EXISTS pg_stat_statements;
CREATE EXTENSION IF NOT EXISTS pg_trgm;
CREATE EXTENSION IF NOT EXISTS fuzzystrmatch;

See Extension Setup for details.

"MCP Server Not Responding"

  1. Check Docker container is running:

    docker ps | grep postgres-mcp

  2. View container logs:

    docker logs <container_id>

  3. Verify environment variable:

    docker exec <container_id> env | grep DATABASE_URI

🚀 Performance Tips

Connection Pooling

Add to DATABASE_URI:

postgresql://user:pass@host:5432/db?pool_size=20&max_overflow=10

SSL/TLS Configuration

For production databases:

postgresql://user:pass@host:5432/db?sslmode=require&sslcert=/path/to/cert

Timeout Configuration

Prevent hanging connections:

postgresql://user:pass@host:5432/db?connect_timeout=10&statement_timeout=30000

📚 Related Documentation

🔗 External Resources

See Home for more tool categories.

Clone this wiki locally