home / mcp / postgres mcp server

Postgres MCP Server

Postgres MCP server with configurable auth

Installation

Add the following to your MCP client configuration file.

Configuration

{
  "mcpServers": {
    "hthuong09-postgres-mcp": {
      "command": "npx",
      "args": [
        "@hthuong09/postgres-mcp",
        "postgres://user:pass@host:5432/dbname"
      ],
      "env": {
        "DEBUG_MCP": "true",
        "DOTENV_PATH": "/path/to/.env",
        "POSTGRES_DB": "mydb",
        "POSTGRES_SSL": "true",
        "POSTGRES_URL": "postgres://user:pass@host:5432/dbname",
        "POSTGRES_HOST": "localhost",
        "POSTGRES_PORT": "5432",
        "POSTGRES_USER": "myuser",
        "POSTGRES_SCHEMA": "public",
        "POSTGRES_PASSWORD": "mypassword"
      }
    }
  }
}

You can query and inspect PostgreSQL databases through a read-only MCP server. This enables you to explore table schemas and fetch column definitions in a safe, structured way without executing write operations against the database.

How to use

Connect to the MCP server from your MCP client to browse database schemas and read table definitions. The server exposes each table as a resource, returning a JSON array of column definitions. Use your standard MCP client workflow to request resources and inspect the resulting schema data.

You can start the server in one of two primary ways: provide a direct Postgres connection URL or configure environment variables and run the command. When you use the URL, you do not need to supply separate host, user, or password values. When you use environment variables, you control the connection details through the specific POSTGRES_* variables and the optional DOTENV_PATH or DEBUG_MCP flags.

How to install

npm install -g @hthuong09/postgres-mcp

Prerequisites: ensure you have Node.js and npm installed on your system. You can verify with node -v and npm -v.

Configuration and usage examples

Use a connection URL to start the MCP server. This is the simplest method if you already have a database URL.

npx @hthuong09/postgres-mcp "postgres://user:pass@host:5432/dbname"

Alternatively, configure environment variables and run the MCP server without passing a URL. This is useful for keeping credentials out of process lists.

export POSTGRES_HOST=localhost
export POSTGRES_DB=mydb
export POSTGRES_USER=myuser
export POSTGRES_PASSWORD=mypassword
npx @hthuong09/postgres-mcp

If you need SSL, enable it via an environment variable.

export POSTGRES_HOST=db.example.com
export POSTGRES_DB=mydb
export POSTGRES_USER=myuser
export POSTGRES_PASSWORD=mypassword
export POSTGRES_SSL=true
npx @hthuong09/postgres-mcp

You can also point to a custom .env file with DOTENV_PATH to load credentials and settings.

DOTENV_PATH=/path/to/.env npx @hthuong09/postgres-mcp

Notes on resources and response format

Each table in the connected database is exposed as a distinct resource. The resource URI follows the pattern that makes it straightforward to fetch schema details, and responses are provided as JSON arrays describing column definitions.

Security considerations

Keep database credentials secure. Prefer environment variables or .env files rather than supplying secrets on the command line in production. Consider enabling SSL for connections in production. The MCP server operates with read-only transactions to prevent data modification.

Development

To build and run locally during development, install dependencies and use the build and run workflows described by your project.

Debugging

Enable debug logging by setting DEBUG_MCP to true. Debug output is written to a temporary path on your platform.