postgresql-ssh

The PostgreSQL SSH MCP Server exposes a secure, Read-Only by default interface for accessing PostgreSQL databases through SSH tunnels. It supports two transports: STDIO for Claude Desktop and a Streamable HTTP API for ChatGPT, enabling flexible integration without exposing databases directly to the network. Core capabilities include an SSH tunnel with auto-reconnect and TOFU, optional OAuth-based authentication for ChatGPT, and a responsive query/administration toolset that leverages a connection pool to manage resources efficiently. Tools are categorized into Query Tools (execute_query, explain_query), Schema Tools (list_schemas, list_tables, describe_table, list_databases), and Admin Tools (get_connection_status, list_active_connections, list_long_running_queries, get_database_version, get_database_size, get_table_stats), giving you a comprehensive set of operations to inspect and query the database safely.

Prerequisites:\n- Node.js and npm installed on your system.\n- Access to a shell with network access to install npm packages.\n\nStep 1: Install dependencies and build (development workflow used in this project).\nbash\nnpm install\n\n\nStep 2: Run the MCP server in development (example for the STDIO/Claude Desktop path).\nbash\n# Start via npx as shown in the Quick Start (no local install required)\nnpx -y @zlash65/postgresql-ssh-mcp\n\n\nStep 3: For production, build the package and run the server (or use Docker as described in the Docker section).\nbash\nnpm run build\nnpm start\n\n\nNotes:\n- Ensure DATABASE_URI or individual connection variables are configured via environment.\n- If using SSH, configure SSH-related environment variables as documented in the Environment Variables section.\n

Tips and common issues:\n- When using SSH tunneling, ensure SSH_HOST, SSH_USER, and either SSH_PRIVATE_KEY_PATH or SSH_PASSWORD are properly set. For deployments behind NAT or firewalls, enable SSH keepalive and increase reconnect attempts as needed.\n- For ChatGPT usage, run the HTTP server behind a TLS proxy or VPN; TLS termination should be handled by your reverse proxy (e.g., nginx) in production.\n- The default READ_ONLY is true; to enable writes, override the READ_ONLY variable.\n- If you encounter issues with max rows or timeouts, adjust MAX_ROWS and QUERY_TIMEOUT in the environment configuration.\n- Use the provided Admin Tools to monitor pool status, active connections, and long-running queries to diagnose performance bottlenecks.\n