PostgreSQL MCP Server

SSE

by henkdz

18 8.2k downloads Not rated yet AGPL-3.0

GitHub Website

About

Integrates with PostgreSQL databases to enable schema management, data migration, performance monitoring, and security configuration through direct database operations without requiring separate management tools.

Details

Repository: HenkDz/postgresql-mcp-server
Transport: SSE
License: AGPL-3.0

Explore

✅ Complete CRUD operations - INSERT/UPDATE/DELETE/UPSERT with parameterized queries
✅ Flexible querying - SELECT with count/exists support and bounded safety limits
✅ Arbitrary SQL execution - Transaction support for complex operations

Setting up with Highlight

This MCP is not yet compatible with Highlight’s one-click setup. However, you can still use it with Highlight by following these steps:

Download and install Highlight from highlightai.com/download
Navigate to the plugins tab and select "Add Custom Plugin"
Configure the plugin with the settings below
Plugin Name PostgreSQL MCP Server

Command (node, npx, python, etc.) npx
Arguments
- Argument 1 @henkey/postgres-mcp-server
- Argument 2 --connection-string
- Argument 3 postgresql://user:password@host:port/database
Please refer to the README for specific instructions on how to obtain API keys or other required environment variables.
Enable "Start Automatically" if you want the plugin to start when Highlight launches

Setting up with Cursor

Open Cursor's settings
Navigate to the MCP section
Click "Add new Global MCP server"
Copy and paste the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

Setting up with Claude Desktop

Open Claude Desktop's settings
Go to the Integrations tab
Click "Add MCP Server"
Use the configuration below based on your operating system

Note: Make sure Claude Desktop is running before attempting to connect.

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

Setting up with Windsurf

Open Windsurf's preferences
Go to the Integrations section
Click "Add MCP Integration"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

Setting up with Cline

Open Cline's settings
Navigate to the Integrations section
Click "Add MCP Server"
Copy and paste the configuration below based on your operating system

Note: Make sure to restart Cline after adding the configuration.

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

Setting up with Goose

Open Goose's preferences
Go to the Integrations tab
Select "MCP Servers"
Click "Add New Server"
Use the configuration below based on your operating system

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "/c",
                "npx",
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "cmd"
        }
    }
}

JSON

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

From the repository

Prerequisites

- Node.js ≥18.0.0
- Access to a PostgreSQL server
- (Optional) An MCP client like Cursor or Claude for AI integration

Install Globally

npm install -g @henkey/postgres-mcp-server

Verify Installation

npx @henkey/postgres-mcp-server --help

Add to your MCP client configuration:

{

  "mcpServers": {

    "postgresql-mcp": {

      "command": "npx",

      "args": [

        "@henkey/postgres-mcp-server",

        "--connection-string", "postgresql://user:password@host:port/database"

      ]

    }

  }

}

Option 2 Install Via Smithery

npx -y @smithery/cli install @HenkDz/postgresql-mcp-server --client claude

Run With Environment Variable

docker run -i --rm \
-e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
postgres-mcp-server



Add to your MCP client configuration:

json
{
"mcpServers": {
"postgresql-mcp": {
"command": "docker",
"args": [
"run",
"-i",
"--rm",
"henkey/postgres-mcp:latest",
"-e",
"POSTGRES_CONNECTION_STRING"
],
"env": {
"POSTGRES_CONNECTION_STRING": "postgresql://user:password@host:port/database"
}
}
}
}

Option 4 Manual Installation Development

bash
git clone <repository-url>
cd postgresql-mcp-server
npm install
npm run build



Add to your MCP client configuration:

json
{
"mcpServers": {
"postgresql-mcp": {
"command": "node",
"args": [
"/path/to/postgresql-mcp-server/build/index.js",
"--connection-string", "postgresql://user:password@host:port/database"
]
}
}
}

Example Usage

typescript
// Analyze database performance
{ "analysisType": "performance", "schema": "public" }

// Create a table with constraints
{
"operation": "create_table",
"tableName": "users",
"columns": [
{ "name": "id", "type": "SERIAL PRIMARY KEY" },
{ "name": "email", "type": "VARCHAR(255) UNIQUE NOT NULL" }
]
}

// Query data with parameters
{
"operation": "select",
"query": "SELECT FROM users WHERE created_at > $1",
"parameters": ["2024-01-01"],
"limit": 100
}
// Select results are always bounded: default limit 100, max 1000.

// Insert new data
{
"operation": "insert",
"table": "users",
"data": {"name": "John Doe", "email": "[email protected]"},
"returning": "",
"maxReturningRows": 100
}
// Mutation RETURNING output is capped in the response: default 100, max 1000.

// Find slow queries
{
"operation": "get_slow_queries",
"limit": 5,
"minDuration": 100
}

// Execute a parameterized SELECT query
{
"operation": "select",
"query": "SELECT * FROM users WHERE id = $1",
"parameters": [1]
}

// Perform an INSERT mutation
{
"operation": "insert",
"table": "products",
"data": {"name": "New Product", "price": 99.99},
"returning": "id",
"maxReturningRows": 100
}

// Perform an UPDATE mutation with a structured WHERE predicate
{
"operation": "update",
"table": "products",
"data": {"price": 89.99},
"where": {"id": 123},
"returning": ["id", "price"]
}

// Manage database object comments
{
"operation": "set",
"objectType": "table",
"objectName": "users",
"comment": "Main user account information table"
}

Docker Usage The PostgreSQL MCP Server is fully Docker-compatible and can be used in production environments. The image uses a multi-stage build, installs only production dependencies in the runtime stage, and runs as the non-root node user. Running With Environment Variables

bash

Basic Usage Using Docker Hub Image

docker run -i --rm \
-e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
henkey/postgres-mcp:latest

With Tools Configuration

docker run -i --rm \
-e POSTGRES_CONNECTION_STRING="postgresql://user:password@host:port/database" \
-e POSTGRES_TOOLS_CONFIG="/app/config/tools.json" \
-v /path/to/config:/app/config \
postgres-mcp-server
```

`Execute Query`

Perform SELECT operations with count/exists support.

`Execute Mutation`

Perform INSERT, UPDATE, DELETE, or UPSERT operations.

`Execute SQL`

Execute arbitrary SQL with transaction support.

`Comments Management`

Manage comments for all database objects.

`Database Analysis`

Analyze database performance and configuration.

`Debug Database`

Troubleshoot database connection, performance, and locks.

`Data Export`

Export data in JSON or CSV format.

`Data Import`

Import data from JSON or CSV files.

`Copy Between Databases`

Transfer data across different databases.

`Real-time Monitoring`

Monitor live database metrics and receive alerts.

npx @henkey/postgres-mcp-server --connection-string "postgresql://readonly_user:pass@host:5432/db"

npx @henkey/postgres-mcp-server --security-mode admin --allow-destructive --connection-string "postgresql://admin_user:pass@host:5432/db"

- Schema Management - Tables, columns, ENUMs, constraints
- User & Permissions - Create users, grant/revoke permissions
- Query Performance - EXPLAIN plans, slow queries, statistics
- Index Management - Create, analyze, optimize indexes
- Functions - Create, modify, manage stored functions
- Triggers - Database trigger management
- Constraints - Foreign keys, checks, unique constraints
- Row-Level Security - RLS policies and management

Brand new capabilities not available in the original 46 tools
- Execute Query - SELECT operations with count/exists support
- Execute Mutation - INSERT/UPDATE/DELETE/UPSERT operations
- Execute SQL - Arbitrary SQL execution with transaction support
- Comments Management - Comprehensive comment management for all database objects

- Database Analysis - Performance and configuration analysis
- Debug Database - Troubleshoot connection, performance, locks
- Data Export - JSON/CSV data export
- Data Import - JSON/CSV data import
- Copy Between Databases - Cross-database data transfer
- Real-time Monitoring - Live database metrics and alerts

Claude Desktop / Cursor

Paste into your MCP client config file to install this server.

{
    "mcpServers": {
        "postgresql mcp server": {
            "env": {},
            "args": [
                "@henkey/postgres-mcp-server",
                "--connection-string",
                "postgresql://user:password@host:port/database"
            ],
            "command": "npx"
        }
    }
}

Linux

{
    "env": [],
    "args": [
        "@henkey/postgres-mcp-server",
        "--connection-string",
        "postgresql://user:password@host:port/database"
    ],
    "command": "npx"
}

Macos

{
    "env": [],
    "args": [
        "@henkey/postgres-mcp-server",
        "--connection-string",
        "postgresql://user:password@host:port/database"
    ],
    "command": "npx"
}

Windows

{
    "env": [],
    "args": [
        "/c",
        "npx",
        "@henkey/postgres-mcp-server",
        "--connection-string",
        "postgresql://user:password@host:port/database"
    ],
    "command": "cmd"
}

A Model Context Protocol (MCP) server that provides comprehensive PostgreSQL database management capabilities for AI assistants.

🚀 What's New: This server has been completely redesigned from 46 individual tools to 18 intelligent tools through consolidation (34→8 meta-tools) and enhancement (+4 new tools), providing better AI discovery while adding powerful data manipulation and comment management capabilities.

Breaking Changes in 2.0.0

Version 2.0.0 introduces security boundaries that intentionally change default behavior from the 1.x line:

- The server starts in readonly mode. Mutations, DDL, role administration, filesystem import/export, and arbitrary SQL require --security-mode write, --security-mode admin, or --security-mode unsafe as appropriate.
- Destructive operations such as drops, resets, broad role grants, and arbitrary SQL require --allow-destructive.
- Per-tool connectionString, sourceConnectionString, and targetConnectionString arguments are disabled by default. Use server-level --connection-string or POSTGRES_CONNECTION_STRING, or explicitly opt in with --allow-tool-connection-string.
- Legacy string where clauses are rejected for mutation, index, export, and copy filters. Use structured where predicates, or rawWhere only with --security-mode unsafe --allow-destructive.
- Multi-statement pg_execute_sql calls must use transactional: true, expectRows: false, and no bind parameters.
- Tool schemas reject unknown fields, so misspelled or unintended inputs fail before connection resolution.
- User and target identifiers are restricted to safe simple PostgreSQL identifiers.

For the non-breaking security patch line, use @henkey/[email protected].

Quick Start

Prerequisites

- Node.js ≥18.0.0 - Access to a PostgreSQL server - (Optional) An MCP client like Cursor or Claude for AI integration

Option 1: npm (Recommended)

```bash

No reviews yet — be the first

Use Google, GitHub, or an email account so ratings stay tied to real people.

Email sign in

No reviews posted yet.

About

Details

Explore

Setting up with Highlight

From the repository

Prerequisites

Install Globally

Verify Installation

Option 2 Install Via Smithery

Run With Environment Variable

Option 4 Manual Installation Development

Example Usage

Docker Usage

Running With Environment Variables

Basic Usage Using Docker Hub Image

With Tools Configuration

Execute Query

Execute Mutation

Execute SQL

Comments Management

Database Analysis

Debug Database

Data Export

Data Import

Copy Between Databases

Real-time Monitoring

Claude Desktop / Cursor

Linux

Macos

Windows

Breaking Changes in 2.0.0

Quick Start

Prerequisites

Option 1: npm (Recommended)

More like this

Redis

Time

Sentry

Github

`Execute Query`

`Execute Mutation`

`Execute SQL`

`Comments Management`

`Database Analysis`

`Debug Database`

`Data Export`

`Data Import`

`Copy Between Databases`

`Real-time Monitoring`