# Postgres MCP

Gives your agent a map of PostgreSQL schemas and safe read-only queries. Useful when the model should read the real database instead of guessing names.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: edelciomolina
- License: not stated · policy=link-only · description only; the file stays with the author
- Source: https://github.com/edelciomolina/postgres-mcp
- Updated: 2026-06-13
- HTML: https://affpapa.org/en/nevibecode/mcp/edelciomolina-postgres-mcp

## What it does

Postgres MCP is a server built on `@modelcontextprotocol/sdk` and `pg`. It assembles a map of your database for the model: schemas, tables, columns, foreign keys, links between tables, plus risk levels and which business domains the data belongs to. All of it comes from the live schema rather than being invented.

Read-only is the default: writes, DDL and arbitrary SQL stay off until you allow them yourself. The `pg_classify_query_risk` tool lets the model check a query for safety before running it. Credentials are resolved from `.env` at startup, so nothing sensitive sits in `mcp.json`. Each tool is opt-in through a `tool=<name>` argument.

You need Node.js 18 or newer and a `.env` file with connection details. Turn on write-capable tools but forget `POSTGRES_MCP_ALLOW_WRITE=true` in `env`, and the server exits at startup — check that before the first connection.

## Requirements
- Needs: Node.js (commands run via npx)
- Environment variables: `MCP_KEY_HOST`, `MCP_KEY_PORT`, `MCP_KEY_NAME`, `MCP_KEY_USER`, `MCP_KEY_PASS`, `MCP_KEY_SSLMODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add --env MCP_KEY_HOST=<MCP_KEY_HOST> --env MCP_KEY_PORT=<MCP_KEY_PORT> --env MCP_KEY_NAME=<MCP_KEY_NAME> --env MCP_KEY_USER=<MCP_KEY_USER> --env MCP_KEY_PASS=<MCP_KEY_PASS> --transport stdio edelciomolina-postgres-mcp -- npx -y @edelciomolina/postgres-mcp
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Codex

**Platform CLI**
```bash
codex mcp add edelciomolina-postgres-mcp --env MCP_KEY_HOST=<MCP_KEY_HOST> --env MCP_KEY_PORT=<MCP_KEY_PORT> --env MCP_KEY_NAME=<MCP_KEY_NAME> --env MCP_KEY_USER=<MCP_KEY_USER> --env MCP_KEY_PASS=<MCP_KEY_PASS> -- npx -y @edelciomolina/postgres-mcp
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "edelciomolina-postgres-mcp": {
            "command": "npx",
            "args": [
                "-y",
                "@edelciomolina/postgres-mcp"
            ],
            "env": {
                "MCP_KEY_HOST": "<MCP_KEY_HOST>",
                "MCP_KEY_PORT": "<MCP_KEY_PORT>",
                "MCP_KEY_NAME": "<MCP_KEY_NAME>",
                "MCP_KEY_USER": "<MCP_KEY_USER>",
                "MCP_KEY_PASS": "<MCP_KEY_PASS>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "edelciomolina-postgres-mcp": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@edelciomolina/postgres-mcp"
            ],
            "env": {
                "MCP_KEY_HOST": "<MCP_KEY_HOST>",
                "MCP_KEY_PORT": "<MCP_KEY_PORT>",
                "MCP_KEY_NAME": "<MCP_KEY_NAME>",
                "MCP_KEY_USER": "<MCP_KEY_USER>",
                "MCP_KEY_PASS": "<MCP_KEY_PASS>"
            }
        }
    }
}
```
Replace <…> with your own values. 1 more environment variable is in the server README

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add -e MCP_KEY_HOST=<MCP_KEY_HOST> -e MCP_KEY_PORT=<MCP_KEY_PORT> -e MCP_KEY_NAME=<MCP_KEY_NAME> -e MCP_KEY_USER=<MCP_KEY_USER> -e MCP_KEY_PASS=<MCP_KEY_PASS> edelciomolina-postgres-mcp npx -y @edelciomolina/postgres-mcp
```
Replace <…> with your own values. 1 more environment variable is in the server README

## When to use it
- read the real schema before writing a query
- check a query for risk before running it
- let the agent reach PostgreSQL without write access
- connect through a `DATABASE_URL` connection string
- expose only the database tools you pick

## Example prompts
- Show me the `orders` table schema and its foreign keys
- Check this query for risk before running it
- Connect to the database and describe which domains the tables belong to

## Similar
- [postgres-patterns](https://affpapa.org/en/nevibecode/skills/postgres-patterns.md) — skill · 5200 installs
- [postgres-best-practices](https://affpapa.org/en/nevibecode/skills/neondatabase-postgres-best-practices.md) — skill · 1900 installs
- [postgres](https://affpapa.org/en/nevibecode/skills/sanjay3290-postgres.md) — skill · 620 installs
- [design-postgres-tables](https://affpapa.org/en/nevibecode/skills/design-postgres-tables.md) — skill · 613 installs
- [postgres-nio](https://affpapa.org/en/nevibecode/skills/postgres-nio.md) — skill · ★ 62
- [migrate-postgres-tables-to-hypertables](https://affpapa.org/en/nevibecode/skills/migrate-postgres-tables-to-hypertables.md) — skill · 355 installs

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md