PostgreSQL SSH MCP Server

[![npm version][npm-version-badge]][npm-package] [![npm downloads][npm-downloads-badge]][npm-package] [![license][license-badge]][license-link]

A secure PostgreSQL MCP server with built-in SSH tunneling. Connect to databases through bastion hosts automatically — no manual ssh -L required.

Features

• Dual Transport — STDIO for Claude Desktop, Streamable HTTP for ChatGPT
• SSH Tunneling — Built-in tunnel with auto-reconnect and TOFU (trust on first use)
• Read-Only by Default — Safe for production; enable writes explicitly
• OAuth Support — Auth0 integration for secure ChatGPT connections
• Connection Pooling — Efficient resource management with configurable limits

---

Architecture

---

Quick Start

Claude Desktop (STDIO)

Add to your Claude Desktop config:

Platform	Config Location
macOS	~/Library/Application Support/Claude/claude_desktop_config.json
Windows	%APPDATA%/Claude/claude_desktop_config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@zlash65/postgresql-ssh-mcp"],
      "env": {
        "DATABASE_URI": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

ChatGPT (Streamable HTTP)

DATABASE_URI="postgresql://user:pass@localhost:5432/mydb" npx @zlash65/postgresql-ssh-mcp-http

Then configure ChatGPT to connect to https://your-subdomain.example.com/mcp.

Note: ChatGPT requires HTTPS. Use a tunnel (ngrok, Cloudflare Tunnel) for local testing.

---

Available Tools

Query Tools

Tool	Description
execute_query	Execute SQL with parameterized queries. Results capped by MAX_ROWS.
explain_query	Get EXPLAIN plans in text, JSON, YAML, or XML format. Supports ANALYZE.

Schema Tools

Tool	Description
list_schemas	List database schemas. Excludes system schemas by default.
list_tables	List tables with row counts and sizes. Optionally include views.
describe_table	Get columns, constraints, and indexes for a table.
list_databases	List all databases with owner, encoding, and size.

Admin Tools

Tool	Description
get_connection_status	Get pool stats, tunnel state, and connection info.
list_active_connections	Show active connections from pg_stat_activity.
list_long_running_queries	Find queries running longer than a threshold.
get_database_version	Get PostgreSQL server version.
get_database_size	Get database size and largest tables.
get_table_stats	Get vacuum/analyze stats and scan counts for a table.

---

Environment Variables

Database Connection

Variable	Required	Default	Description
DATABASE_URI	Yes*	—	Full connection string (e.g., postgresql://user:pass@host:5432/db)
DATABASE_HOST	Yes*	—	Database hostname
DATABASE_PORT	No	5432	Database port
DATABASE_NAME	Yes*	—	Database name
DATABASE_USER	Yes*	—	Database username
DATABASE_PASSWORD	Yes*	—	Database password

*Either DATABASE_URI or all individual connection variables are required.

SSL Configuration

Variable	Default	Description
DATABASE_SSL	Auto	true or false. Auto-enabled for non-localhost.
DATABASE_SSL_CA	—	Path to CA certificate bundle
DATABASE_SSL_REJECT_UNAUTHORIZED	true	Set false to allow self-signed certificates

SSH Tunnel

Variable	Required	Default	Description
SSH_ENABLED	No	false	Set true to enable SSH tunneling
SSH_HOST	Yes*	—	SSH server hostname
SSH_PORT	No	22	SSH server port
SSH_USER	Ye

... View full README on GitHub