PostgreSQL MCP Server

How to use

Connect your MCP client to the server using an MCP configuration that runs the MCP server locally or remotely. You can start the server via npm/npx or Docker, then interact with it through your MCP client to perform a wide range of database operations. Practical workflows include analyzing performance, creating tables with constraints, executing parameterized SELECT queries, inserting or updating records, and managing comments on database objects. All actions are performed through structured tool calls that ensure safety and parameterization.

How to install

Prerequisites you need before installing: - Node.js ≥ 18.0.0 - Access to a PostgreSQL server - Optional: An MCP client like Cursor for AI integration

# Option 1: Install via npm (recommended)
# Install globally
npm install -g @henkey/postgres-mcp-server

# Or run directly with npx (no installation)
# Optional: set the connection string via environment variable
export POSTGRES_CONNECTION_STRING="postgresql://user:pass@localhost:5432/db"
npx @henkey/postgres-mcp-server
# Or pass directly
npx @henkey/postgres-mcp-server --connection-string "postgresql://user:pass@localhost:5432/db"

# Verify installation
npx @henkey/postgres-mcp-server --help

Option 1 configuration example for your MCP client:

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

Additional installation options

Option 2: Install via Smithery. This streamlines client integration for Claude Desktop or similar MCP clients.

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

Option 3: Docker (recommended for production). Build or pull the image and run with the required connection string.

# Build the image locally
docker build -t postgres-mcp-server .

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

Option 3b: If you prefer the official image, you can pull and run that as well.

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

Option 4: Manual installation (development). Clone the project, install dependencies, and build locally.

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

Manual runtime example for local development to run the built server locally with a connection string.

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

Configuration and startup notes

Your MCP client configuration should reference the running MCP server so the AI assistant can issue PostgreSQL operations. Ensure the connection string is correct and that network access between the MCP client and the server is allowed. For production deployments, prefer Docker to isolate the runtime and simplify scaling.

Environment variable you need to supply: - POSTGRES_CONNECTION_STRING — the PostgreSQL connection string in the format postgresql://user:password@host:port/database. Use placeholders in examples where needed.

Security and usage notes

All operations use parameterized queries to prevent SQL injection. The server supports flexible connection options, including environment-based configuration and per-tool configuration, with robust error handling and connection pooling to maintain reliability in production.

Troubleshooting tips

If you cannot start the MCP server, verify that Node.js is installed at the required version, the PostgreSQL server is reachable, and the connection string is correctly formatted. Check logs for startup errors related to the connection or missing environment variables.

Schema Management

Manage tables, columns, ENUMs, and constraints.

User & Permissions

Create users and grant or revoke permissions.

Query Performance

Analyze query plans, identify slow queries, and inspect statistics.

Index Management

Create, analyze, and optimize indexes.

Functions

Create and manage stored functions.

Triggers

Manage database triggers.

Constraints

Manage foreign keys, checks, and unique constraints.

Row-Level Security

Manage RLS policies and security controls.

Execute Query

Run SELECT operations with count/exists support.

Execute Mutation

Perform INSERT/UPDATE/DELETE/UPSERT operations.

Execute SQL

Execute arbitrary SQL with transaction support.

Comments Management

Manage comments for database objects.

Database Analysis

Analyze performance and configuration.

Debug Database

Troubleshoot connections, performance, and locks.

Data Export/Import

Migrate data via JSON/CSV formats.

Copy Between Databases

Transfer data across databases.

Real-time Monitoring

Provide live metrics and alerts.