SQL

You can run a SQL MCP Server that lets language models and MCP clients query PostgreSQL databases securely, optionally through SSH bastion tunnels. It supports read-only PostgreSQL operations, STDIO-based MCP transport, and easy configuration through environment variables for local, containerized, or AI-driven workflows.

How to use

Set up a local or remote MCP client to interact with the Postgres MCP server. You will run the MCP server as a stdio process and issue SQL queries through the MCP interface. You can connect directly with a local Postgres instance or through an SSH bastion to a private database, depending on your network setup. The server speaks the MCP protocol over STDIO, so your client communicates by sending structured tool calls that translate into SQL queries.

Typical usage patterns include connecting to a local or remote PostgreSQL database, issuing read-only queries such as SELECT statements, and receiving structured results that you can render in your UI or analyze in your tooling. If you need private network access, enable SSH tunneling and provide the bastion connection details so the server can reach your database through the tunnel.

How to install

Prerequisites: you need Node.js and npm installed on your machine. You also need git to clone the project. Ensure you have network access to install dependencies.

# Clone the project repository
git clone https://github.com/your-org/sql-mcp-server.git
cd sql-mcp-server

# Install dependencies
npm install

# Build the TypeScript project
npm run build

Configure environment variables as needed for your environment. You can start with a local PostgreSQL instance and no SSH tunnel, or enable an SSH bastion for private networks. The following variables configure a typical local setup.

DB_USER=postgres
DB_PASS=yourpassword
DB_HOST=localhost
DB_PORT=5432
DB_NAME=mydatabase
USE_SSH_TUNNEL=true
SSH_BASTION_HOST=bastion.example.com
SSH_BASTION_USER=ec2-user
SSH_PRIVATE_KEY_PATH=~/.ssh/id_rsa

Start the MCP server via the recommended runtime command. The server runs through a standard MCP client interface using STDIO. Use the connection string to your database with or without a tunnel depending on your setup.

npx -y @modelcontextprotocol/server-postgres postgresql://<user>:<pass>@localhost:5433/<dbname>

If you prefer a direct connection without SSH tunneling, provide the database host and port via environment variables and run the same MCP start command with the updated connection URL.

DB_HOST=rds-host.amazonaws.com DB_PORT=5432 npx -y @modelcontextprotocol/server-postgres postgresql://<user>:<pass>@rds-host.amazonaws.com/<dbname>

Additional notes

The server supports PostgreSQL read-only queries and can be accessed securely through SSH bastion tunnels when needed. It adheres to the Model Context Protocol (MCP) and communicates over STDIO, making it suitable for local development, containerized workflows, and AI-driven tooling.

Security and configuration notes

Use SSH bastion access only if your PostgreSQL database is not publicly reachable. Keep SSH keys secure and limit access to trusted hosts. When running in production, consider limiting database user permissions to read-only to prevent any modification of data.

Available tools

STDIO MCP Transport

Provides the STDIO-based MCP protocol transport allowing the MCP client to communicate with the server via standard input and output.

PostgreSQL Read-Only Engine

Executes read-only SQL queries against PostgreSQL using the pg library.

SSH Bastion Tunneling

Supports SSH bastion access to private RDS instances via SSH tunnels for secure connectivity.

Environment Variable Configuration

Configures database connection and tunneling via a .env file or environment variables.

Jest Testability

Includes testable mocks and Jest-based tests for reliable behavior.