mcp-postgres

A comprehensive PostgreSQL MCP (Model Context Protocol) server providing 27 tools for database management and administration.

Features

• Connection Management — connect, disconnect, pool health monitoring
• Query Execution — parameterized queries, EXPLAIN ANALYZE, prepared statements
• Schema Introspection — tables, indexes, constraints, views, functions, enums, extensions
• CRUD Operations — type-safe insert, update, delete, upsert with injection protection
• Server Management — version, settings, config reload, uptime
• Database Sizing — database and table sizes with index/toast breakdown

Installation

npm install @itunified.io/mcp-postgres

Or run directly:

npx @itunified.io/mcp-postgres

Configuration

Set one of the following environment variables:

# Option 1: Connection string (preferred)
export POSTGRES_CONNECTION_STRING="postgresql://myuser:mypassword@your-database.example.com:5432/mydb"

# Option 2: Individual variables
export PGHOST="your-database.example.com"
export PGPORT="5432"
export PGUSER="myuser"
export PGPASSWORD="mypassword"
export PGDATABASE="mydb"
export PGSSLMODE="require"  # optional

Multi-Database Configuration

Create a config file at ~/.config/mcp-postgres/databases.yaml:

databases:
  production:
    host: db.example.com
    port: 5432
    user: admin
    password: ${DB_PROD_PASSWORD}
    database: myapp
    ssl: true
  staging:
    host: staging-db.example.com
    port: 5432
    user: admin
    password: ${DB_STAGING_PASSWORD}
    database: myapp
default: production

Environment variables in ${VAR_NAME} syntax are automatically expanded.

Config file discovery order:

1. POSTGRES_CONFIG_FILE env var (explicit path)
2. ~/.config/mcp-postgres/databases.yaml or databases.json
3. POSTGRES_CONNECTION_STRING env var (single database)
4. Individual PG* env vars (single database)

Override the config path with POSTGRES_CONFIG_FILE env var:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["@itunified.io/mcp-postgres"],
      "env": {
        "POSTGRES_CONFIG_FILE": "/path/to/databases.yaml"
      }
    }
  }
}

Use pg_list_connections to see all configured databases, pg_switch_database to change the active one.

HashiCorp Vault Integration (Optional)

mcp-postgres supports opportunistic secret loading from HashiCorp Vault via AppRole authentication. When configured, it fetches PostgreSQL credentials from a KV v2 path — so you never need to put database passwords in environment variables or config files.

How it works:

1. On startup, the server checks for NAS_VAULT_ADDR, NAS_VAULT_ROLE_ID, and NAS_VAULT_SECRET_ID in the environment
2. If all three are set, it logs in via AppRole and reads the configured KV v2 path
3. It populates POSTGRES_CONNECTION_STRING and PG* env vars from the Vault secret — but only for vars not already set
4. If Vault is not configured or unreachable, the server silently falls back to env vars

Precedence: Explicit env vars → Vault → config file fallback → (error if nothing set)

* Only required if using Vault. Without these, the server uses env vars / config files directly.

Vault KV v2 secret structure:

# Path: kv/your/postgres/secret
{
  "connection_string": "postgresql://myuser:mypassword@your-database.example.com:5432/

... [View full README on GitHub](https://github.com/itunified-io/mcp-postgres#readme)