MCP PostgreSQL Server

0.1.3 verified Sat Apr 25 auth: no javascript

A Model Context Protocol (MCP) server that enables AI models, particularly Claude, to interact with PostgreSQL databases through standardized tools like query, execute, list_schemas, list_tables, and describe_table. Version 0.1.3 is the latest stable release, currently in early development with active updates. It supports both PostgreSQL-style ($1, $2) and MySQL-style (?) parameter placeholders for prepared statements, multi-schema operations, and TypeScript types. Unlike generic database MCP servers, it is purpose-built for PostgreSQL, offering secure connection handling via environment variables and automatic cleanup. It is designed for use with MCP-compatible hosts (e.g., Claude Desktop) and should not be confused with direct database client libraries.

Common errors

error Error: Cannot find module 'mcp-postgres-server' ↓

cause Package not installed or npx not used correctly.

fix

Run 'npm install mcp-postgres-server' globally or use 'npx -y mcp-postgres-server'.

error Error: getaddrinfo ENOTFOUND your_host ↓

cause The PG_HOST environment variable is not set or points to an unreachable host.

fix

Ensure PG_HOST is set to a valid PostgreSQL hostname or IP address in the environment.

Warnings

breaking Environment variables must be set before starting the server or the connection will fail. ↓

fix Set PG_HOST, PG_PORT, PG_USER, PG_PASSWORD, PG_DATABASE in the environment or MCP client config.

gotcha The package does not support connection pooling; each tool call opens a new connection, which can be slow. ↓

fix Use connection pooling externally or consider alternative MCP servers for high-throughput scenarios.

gotcha The 'connect_db' tool is redundant; the server auto-connects using environment variables. Calling connect_db may conflict. ↓

fix Avoid using the connect_db tool unless you need to override connection parameters per request.

Install

npm install mcp-postgres-server

yarn add mcp-postgres-server

pnpm add mcp-postgres-server

Imports

default
wrong
```
const server = require('mcp-postgres-server')
```
correct
```
import server from 'mcp-postgres-server'
```
Package exports a single default MCP server instance, not a class. Use ESM import.
Server
wrong
```
import Server from 'mcp-postgres-server'
```
correct
```
import { Server } from 'mcp-postgres-server'
```
Named export Server allows creating custom instances, but most users will use the default export.

Quickstart

Runs the MCP PostgreSQL server via npx and shows the required environment variable configuration for MCP client integration.

npx mcp-postgres-server

# Then configure in your MCP client (e.g., Claude Desktop):
# {
#   "mcpServers": {
#     "postgres": {
#       "type": "stdio",
#       "command": "npx",
#       "args": ["-y", "mcp-postgres-server"],
#       "env": {
#         "PG_HOST": process.env.PG_HOST ?? 'localhost',
#         "PG_PORT": process.env.PG_PORT ?? '5432',
#         "PG_USER": process.env.PG_USER ?? 'postgres',
#         "PG_PASSWORD": process.env.PG_PASSWORD ?? '',
#         "PG_DATABASE": process.env.PG_DATABASE ?? 'mydb'
#       }
#     }
#   }
# }