MCP Configuration

📋 Prerequisites

🔧 Configuration by Client

Claude Desktop

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

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

Cursor IDE

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

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

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

Unrestricted Mode (Development)

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

🌍 Environment Variables

DATABASE_URI (Required)

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

# 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 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

list_schemas()

Step 2: Check Extensions

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

Step 3: Test Security Mode

execute_sql(sql="DROP TABLE test")

🐳 Docker Configuration

Docker Run with Environment File

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

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

Docker Compose

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;

"MCP Server Not Responding"

🚀 Performance Tips

Connection Pooling

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

SSL/TLS Configuration

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

Timeout Configuration

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

📚 Related Documentation

🔗 External Resources