postgres

This MCP server exposes PostgreSQL database resources via two transports: HTTP and Stdio. The HTTP transport (Streamable HTTP Server Transport) provides a REST-like interface that can be consumed by web clients and integrations, supports session management, and can be deployed behind a web service. The Stdio transport offers a CLI-style interface for direct interaction in development or automation scripts. Core resources include a hello endpoint for testing, a database Tables resource to list tables, a Tables/Schema resource to inspect columns, and a read-only Query tool to execute SQL against the configured PostgreSQL database. To start, run the server with npx, choosing either the default HTTP transport or the stdio transport by appending stdio. Configure credentials via environment variables (POSTGRES_*, PORT, HOST, CORS_ORIGIN, NODE_ENV) or a .env file as described in the repository. Once running, you can access the HTTP API at http://<HOST>:<PORT>/mcp (default port 3000) and use the MCP Inspector or Claude Desktop tooling to interact with resources and run read-only queries.

Prerequisites:

• Node.js and npm installed
• Access to npm (public internet)

Installation steps:

1. Ensure Node.js and npm are installed:
   • On macOS/Linux: curl -fsSL https://deb.nodesource.com/setup_current.x | bash - && sudo apt-get install -y nodejs
   • On Windows: install Node.js from https://nodejs.org/
2. Install or use npx to run the MCP server package directly without a global install:
   • npx @ahmedmustahid/postgres-mcp-server
3. Prepare environment variables:
   • Create a .env file or export variables as shown in the Quick Start document: POSTGRES_URL, POSTGRES_USERNAME, POSTGRES_PASSWORD, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DATABASE, PORT, HOST, CORS_ORIGIN, NODE_ENV
4. Start the HTTP transport:
   • npx @ahmedmustahid/postgres-mcp-server
5. Start the Stdio transport (alternative CLI transport):
   • npx @ahmedmustahid/postgres-mcp-server stdio

If you prefer containerized deployment, you can use the provided Docker/Podman setup described in the repository.

Tips and notes:

• The HTTP transport supports sessions; in production, consider a persistent session store rather than in-memory sessions.
• If you see a port conflict, update PORT in your environment or .env file and restart.
• The database credentials can be supplied either as a single POSTGRES_URL connection string or as individual components (POSTGRES_USERNAME, POSTGRES_PASSWORD, POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DATABASE).
• For the HTTP endpoint health checks, a GET request to /health confirms responsiveness (returns 405 on other methods).
• The REST API exposes resources such as database://tables and database://tables/{tableName}/schema, plus a hello://world resource for testing.
• When using Docker/Podman, ensure you expose the correct ports and set environment variables inside the container as needed.