English | 🌐 Português

Postgres MCP 🔌 Native MCP server for PostgreSQL - reads credentials from .env at runtime with flexible key mapping, configurable tool selection, and read-only mode by default.

✨ What it does

Most LLMs interact with databases by guessing - assuming table names, inventing column names, and writing queries that may fail or expose sensitive data. Postgres MCP solves this by giving the LLM a structured, safe interface to actually understand the database before touching it.

Built with @modelcontextprotocol/sdk and pg, it provides:

• 🧠 Semantic knowledge graph - the LLM gets a complete map of schemas, tables, columns, foreign keys, inferred relations, risk levels, and business domains - built from the real schema, not invented
• 🛡️ Read-only by default - no writes, no DDL, no arbitrary SQL unless you explicitly opt in; pg_classify_query_risk lets the LLM check a query's safety before running it
• 🔐 Runtime credential resolution - credentials are read from .env at startup; nothing sensitive lives in mcp.json
• 🎯 Explicit tool selection - every tool is opt-in via tool=<name> args, so the LLM only sees what you choose to expose

📋 Requirements

• ⚙️ Node.js >= 18
• 📄 A .env file with database credentials (anywhere in the project tree - see .env Discovery)

🚀 Installation

There are two ways to use this package. Choose the one that best fits your workflow.

Option 1 - No installation (via npx, recommended for quick start)

No installation needed. npx downloads and runs the package on demand. Add -y as the first argument to skip the confirmation prompt.

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edelciomolina/postgres-mcp"
      ],
      "env": {
        "MCP_KEY_HOST":    "DB_HOST",
        "MCP_KEY_PORT":    "DB_PORT",
        "MCP_KEY_NAME":    "DB_NAME",
        "MCP_KEY_SSLMODE": "DB_SSLMODE",
        "MCP_KEY_USER":    "DB_USER",
        "MCP_KEY_PASS":    "DB_PASS"
      }
    }
  }
}

This starts the server with the default read-only tool set - no tool= arguments needed. To enable write-capable tools, see Write-capable tools.

💡 Using Supabase, Neon, Railway or another platform that only provides a connection string? Use MCP_KEY_URL pointing to DATABASE_URL (or whatever variable name the platform uses). The server will prioritize the URL and ignore the individual variables. See Connection via URL.

Option 2 - Install via VS Code (MCP extension marketplace)

VS Code supports discovering and installing MCP servers directly in the editor, without using the terminal.

1. Open the Command Palette (Cmd+Shift+P on Mac / Ctrl+Shift+P on Windows/Linux)
2. Run MCP: Add Server
3. Choose **"Browse MCP Serv

... View full README on GitHub