home / mcp / postgres mcp server

Postgres MCP Server

MCP (Model Context Protocol) Server for postgres Database

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "ahmedmustahid-postgres-mcp-server": {
      "url": "http://localhost:3000/mcp",
      "headers": {
        "HOST": "0.0.0.0",
        "PORT": "3000",
        "NODE_ENV": "development",
        "CORS_ORIGIN": "http://localhost:8080,http://localhost:3000",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_DATABASE": "your_database",
        "POSTGRES_PASSWORD": "your_password",
        "POSTGRES_USERNAME": "your_username"
      }
    }
  }
}

You run a dual-transport MCP server that exposes PostgreSQL resources and a read-only query tool via both HTTP and Stdio, so you can integrate with web apps or run ad-hoc queries from the command line. This setup is production-ready, supports session management on HTTP, and can be deployed with containers for flexible environments.

How to use

Start by running the MCP server in one of the two supported transports. For HTTP usage, you run the server to expose a REST-like interface that you can access from web clients or your own frontend. For Stdio usage, you run the server as a local CLI service that you can drive directly from scripts or terminal sessions.

Common workflows include listing database tables, inspecting table schemas, and executing read-only SQL queries against your PostgreSQL database. Use the HTTP transport when you want multi-user sessions, web compatibility, and easy integration with frontend apps. Use the Stdio transport for quick, script-based access or during local development.

You can verify the server is reachable by hitting the health endpoint on the HTTP transport and by testing the CLI path for the Stdio transport. If you use the HTTP route, connect to http://localhost:3000/mcp and perform your queries or resource lookups through your client of choice.

How to install

# Prerequisites
node.js and npm must be installed on the system

# 1) Install and run the HTTP MCP server (default streamable HTTP)
npx @ahmedmustahid/postgres-mcp-server

# 2) Run the Stdio MCP server
npx @ahmedmustahid/postgres-mcp-server stdio

Configuration and usage notes

Environment variables configure the PostgreSQL connection and server behavior. You provide credentials and host information, then run the MCP server. The key variables are POSTGRES_USERNAME, POSTGRES_PASSWORD, POSTGRES_HOST, and POSTGRES_DATABASE. You can also set server options like PORT, HOST, CORS_ORIGIN, and NODE_ENV.

# PostgreSQL connection details
POSTGRES_USERNAME=your_username
POSTGRES_PASSWORD=your_password
POSTGRES_HOST=localhost
POSTGRES_DATABASE=your_database

# HTTP server configuration
PORT=3000
HOST=0.0.0.0

# CORS origins (comma-separated)
CORS_ORIGIN=http://localhost:8080,http://localhost:3000

# Environment
NODE_ENV=development

Resources and tools

The MCP server exposes a few built-in resources to explore the PostgreSQL database and a tool to run read-only queries.

Available tool: query executes read-only SQL against the connected database.

Health checks and troubleshooting

Health: The HTTP server exposes a /health endpoint. A GET request should respond to indicate the server is running and responsive.

Troubleshooting tips include verifying database connectivity, ensuring the port is not in use, and reviewing environment variable values. If the HTTP server cannot connect to PostgreSQL, double-check POSTGRES_* values and that PostgreSQL is reachable from the MCP host.

Transport differences

HTTP transport supports stateful sessions and multiple concurrent clients, suitable for web integrations and REST-like usage. Stdio transport is stateless, designed for CLI-style direct interaction and single-process use.

Development notes

To add new resources or tools, create the appropriate files under the src/resources and src/tools directories, register them in the server, and ensure the build/run flow is compatible with your deployment target.