MCP PostgreSQL Server

A simple MCP server for PostgreSQL with query filtering system.

Repository: https://github.com/deadraid/mcp-postgresql NPM Package: https://www.npmjs.com/package/mcp-postgresql Author: deadraid License: MIT

Installation

# Install globally from npm
npm install -g mcp-postgresql

# Or use directly with npx (no installation needed)
npx mcp-postgresql

Features

• 3 tools: query, schema, tables
• Query filtering: 4 access levels (readonly, modify, ddl, custom)
• Data masking: Automatic masking of sensitive fields (passwords, emails, etc.)
• Security filtering: Hide tables and columns by configuration
• Universal tool: One query instead of multiple separate tools
• Simple configuration: Only through environment variables
• SSL support: Full SSL/TLS configuration for secure connections
• URL connection: Support for PostgreSQL connection strings
• Production ready: Available on npm, used in production environments

Quick Start

# Install from npm (recommended)
npm install -g mcp-postgresql

# Or use directly with npx (no installation needed)
npx mcp-postgresql

Installation

From npm (recommended)

# Install globally from npm registry
npm install -g mcp-postgresql

# Or use directly with npx (no installation needed)
npx mcp-postgresql

From source (for development)

git clone https://github.com/deadraid/mcp-postgresql.git
cd mcp-postgresql
npm install
npm run build
npm link  # For development

Usage

Basic Configuration

Using local build

{
  "mcpServers": {
    "postgresql": {
      "command": "node",
      "args": ["path/to/mcp-postgresql/dist/index.js"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "mydb",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "password",
        "POSTGRES_QUERY_LEVEL": "readonly"
      }
    }
  }
}

Using global installation

{
  "mcpServers": {
    "postgresql": {
      "command": "mcp-postgresql",
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "mydb",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "password",
        "POSTGRES_QUERY_LEVEL": "readonly"
      }
    }
  }
}

Using npx (recommended)

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["mcp-postgresql-server"],
      "env": {
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "mydb",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "password",
        "POSTGRES_QUERY_LEVEL": "readonly"
      }
    }
  }
}

Advanced Configuration with SSL

Using connection URL (recommended for cloud databases)

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["mcp-postgresql-server"],
      "env": {
        "POSTGRES_URL": "postgresql://user:password@host:port/database?sslmode=require",
        "POSTGRES_QUERY_LEVEL": "readonly"
      }
    }
  }
}

Using SSL certificates

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["mcp-postgresql-server"],
      "env": {
        "POSTGRES_HOST": "your-db-host.com",
        "POSTGRES_PORT": "5432",
        "POSTGRES_DB": "mydb",
        "POSTGRES_USER": "postgres",
        "POSTGRES_PASSWORD": "password",
        "POSTGRES_SSL": "true",
        "POSTGRES_SSL_CA": "/path/to/ca-cert.pem",
        "POSTGRES_SSL_CERT": "/path/to/client-cert.pem",
        "POSTGRES_SSL_KEY": "/path/to/client-key.pem",
        "POSTGRES_QUERY_LEVEL": "readonly"
      }
    }
  }
}

Access Levels

• readonly - SELECT queries only
• modify - SELECT, INSERT, UPDATE, DELETE
• ddl - All operations including CREATE, DROP, ALTER
• custom - Custom commands via POSTGRES_ALLOWED_COMMANDS

Data Masking and Security Filtering

The server automatically masks sensitive data and can hide specific tables/columns:

Default masked fields (values replaced with ***):

• password, passwd, pwd
• secret, token, api_key, apikey
• private_key, privatekey
• credit_card, creditcard, card_number, cardnumber
• ssn, social_security, tax_id
• email, phone, address

Configuration options:

{
  "mcpServers": {
    "postgresql": {
      "command": "npx",
      "args": ["mcp-postgresql-server"],
      "env": {
        "POSTGRES_URL": "postgresql://user:password@host:port/database",
        "POSTGRES_QUERY_LEVEL": "readonly",
        "POSTGRES_DATA_MASKING": "true", // Enable data masking (default: true)
        "POSTGRES_HIDDEN_TABLES": "secret_table,internal_logs", // Hide specific tables
        "POSTGRES_HIDDEN_COLUMNS": "internal_id,debug_info", // Hide specific columns
        "POSTGRES_SENSITIVE_FIELDS": "custom_field,internal_code" // Additional fields to mask
      }
    }
  }
}

Usage Examples

Execute Query

{
  "name": "query",
  "arguments": {
    "sql": "SELECT * FROM users LIMIT 10"
  }
}

Note: Sensitive fields (passwords, emails, etc.) will be automatically masked with ***

View Schema

{
  "name": "schema",
  "arguments": {
    "table": "users"
  }
}

Note: Hidden tables and columns will be filtered out from results

List Tables

{
  "name": "tables",
  "arguments": {}
}

Note: Hidden tables will be filtered out from results

View Schema

{
  "name": "schema",
  "arguments": {
    "table": "users"
  }
}

List Tables

{
  "name": "tables",
  "arguments": {}
}

Environment Variables

Connection Options

Variable	Description	Default
POSTGRES_URL	Full connection URL (has priority over individual params)	""
POSTGRES_HOST	Database host (ignored if URL is set)	localhost
POSTGRES_PORT	Database port (ignored if URL is set)	5432
POSTGRES_DB	Database name (ignored if URL is set)	postgres
POSTGRES_USER	Database user (ignored if URL is set)	postgres
POSTGRES_PASSWORD	Database password (ignored if URL is set)	""

SSL Configuration

Variable	Description	Default
POSTGRES_SSL	Enable SSL (true, false, or leave empty for auto)	""
POSTGRES_SSL_CA	SSL CA certificate path	""
POSTGRES_SSL_CERT	SSL client certificate path	""
POSTGRES_SSL_KEY	SSL client key path	""
POSTGRES_SSL_REJECT_UNAUTHORIZED	Reject unauthorized SSL certs (false to disable)	""

Security Options

Variable	Description	Default
POSTGRES_QUERY_LEVEL	Access level	readonly
POSTGRES_ALLOWED_COMMANDS	Custom allowed commands	""
POSTGRES_DATA_MASKING	Enable data masking (true/false)	true
POSTGRES_HIDDEN_TABLES	Comma-separated list of tables to hide	""
POSTGRES_HIDDEN_COLUMNS	Comma-separated list of columns to hide	""
POSTGRES_SENSITIVE_FIELDS	Additional fields to mask (comma-separated)	""

SSL Examples

Cloud Database (Supabase, Neon, etc.)

POSTGRES_URL="postgresql://user:password@host:port/database?sslmode=require"

Self-hosted with SSL

POSTGRES_SSL=true
POSTGRES_SSL_CA=/path/to/ca-cert.pem
POSTGRES_SSL_CERT=/path/to/client-cert.pem
POSTGRES_SSL_KEY=/path/to/client-key.pem

Disable SSL verification (for development)

POSTGRES_SSL_REJECT_UNAUTHORIZED=false

Development

# Build
npm run build

# Development mode
npm run dev

# Lint
npm run lint

Links

• NPM Package: https://www.npmjs.com/package/mcp-postgresql
• GitHub Repository: https://github.com/deadraid/mcp-postgresql
• Issues & Support: https://github.com/deadraid/mcp-postgresql/issues

License

MIT