postgres-ssh-mcp

Cross-platform MCP server for PostgreSQL with SSH tunnel support. Works on macOS, Linux, and Windows.

Overview

postgres-ssh-mcp exposes MCP tools that allow AI tools to query and introspect PostgreSQL databases. It supports three connection modes:

Connection Modes

Using with AI Tools

Any MCP-Compatible Tool

Tools such as Claude Desktop, Cursor, and Windsurf use a JSON config file. Add an entry under mcpServers:

{
  "mcpServers": {
    "postgres-ssh-mcp": {
      "command": "npx",
      "args": ["-y", "postgres-ssh-mcp"],
      "env": {
        "DB_HOST": "localhost",
        "DB_NAME": "mydb",
        "DB_USER": "dbuser",
        "DB_PASSWORD": "dbpassword",
        
        // If you have an SSH config alias:
        "SSH_HOST": "my-bastion",
        
        // Or if you need explicit SSH:
        "SSH_HOSTNAME": "127.0.0.1",
        "SSH_USER": "mybastionuser",
        "SSH_IDENTITY_FILE": "~/.ssh/mybastionkey", // optional if you use the default key path
        "SSH_KEY_PASSPHRASE": "mypassphrase", // optional, if your private key is encrypted
        "SSH_PORT": "1234", // defaults to 22
      }
    }
  }
}

For SSH tunnel connections, add SSH_HOST (SSH config alias) or SSH_HOSTNAME + SSH_USER (explicit credentials) to the env block.

Claude Code

Use claude mcp add to register the server. All environment variables must be passed via --env flags.

claude mcp add --transport stdio postgres-ssh-mcp \
  --env DB_HOST=localhost \
  --env DB_NAME=mydb \
  --env DB_USER=dbuser \
  --env DB_PASSWORD=dbpassword \
  -- npx -y postgres-ssh-mcp

Hint: You can include --scope project to add the server only to the current project.

Tools

Defense-in-Depth Query Safety

This is the key feature that sets postgres-ssh-mcp apart from other PostgreSQL MCP servers. It is the only one that enforces multi-layered protection against unintended data modifications through a combination of safety mechanisms.

1. AST-level SQL validation using pgsql-parser and @pgsql/traverse — parses SQL into an abstract syntax tree and walks it to detect mutations, including hidden ones in CTEs, SELECT INTO, and locking clauses. Only SELECT and EXPLAIN statements are allowed.
2. Dangerous function denylist — blocks 250+ PostgreSQL functions that can cause side effects even inside read-only transactions, including pg_sleep, nextval, pg_notify, file I/O functions, advisory locks, and replication controls.
3. Read-only transaction wrapping — all queries execute inside BEGIN TRANSACTION READ ONLY with automatic ROLLBACK.
4. Single-statement enforcement — multi-statement queries are rejected before execution.

Note: Disabling these safety mechanisms is not recommended, however, you can do so by setting DB_READ_ONLY=false, which grants AI tools full write access to the database.

Environment Variables

These are all environment variables that can be used to configure this MCP server.

Required

Optional

Development

Copy the example env file and fill in your values:

git clone https://github.com/SecretX33/postgres-ssh-mcp.git
cd postgres-ssh-mcp
npm install
npm run build

The compiled server is written to dist/index.js.

Copy the example env file and fill in your values:

cp .env.example .env
# edit .env

Then run in watch mode (automatically loads .env):

npm run dev

License

MIT