Postgres MCP Server

🌐 English | Português

---

✨ What it does

This is a native MCP server built directly with @modelcontextprotocol/sdk and pg (node-postgres). It provides:

• 🔐 Runtime credential resolution - reads database credentials from your .env file at startup, so no secrets are stored in mcp.json
• 🗝️ Flexible key mapping - use any .env variable names; tell the server which ones to use via env in mcp.json
• 🎯 Explicit tool selection - pass tool=<name> args to choose exactly which MCP tools to expose
• 🛡️ Read-only by default - if no tools are specified, only safe introspection tools are enabled (no writes, no arbitrary SQL execution)

---

📋 Requirements

• ⚙️ Node.js >= 18
• 📄 A .env file with the 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 install (via npx, recommended for quick start)

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

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edelciomolina/postgres-mcp",
        "tool=pg_manage_query",
        "tool=pg_manage_schema",
        "tool=pg_manage_indexes",
        "tool=pg_monitor_database"
      ],
      "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"
      }
    }
  }
}

---

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

VS Code supports discovering and installing MCP servers directly from the editor, without touching 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 "Browser MCP Servers" (or "From registry", depending on your VS Code version)
4. Search for postgres-mcp or edelciomolina
5. Select Postgres MCP and follow the prompts - VS Code will add the entry to your mcp.json automatically

💡 You can also open the MCP Servers panel via the Copilot chat icon → Manage MCP Servers to browse, enable, or disable servers at any time.

After installing, edit the generated entry in .vscode/mcp.json to add your tool= args and env key mappings as shown in the Usage section below.

---

🚀 Usage in VS Code (mcp.json)

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "@edelciomolina/postgres-mcp",
        "tool=pg_manage_query",
        "tool=pg_manage_schema",
        "tool=pg_manage_indexes",
        "tool=pg_monitor_database"
      ],
      "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"
      }
    }
  }
}

The corresponding .env in your project root:

DB_HOST=db.your-project.supabase.co
DB_PORT=5432
DB_NAME=postgres
DB_SSLMODE=require
DB_USER=readonly_user
DB_PASS=your_password

---

⚙️ How mcp.json configuration works

🗝️ env - credential key mapping

The env block does not contain the actual credentials. It maps each MCP_KEY_* to the name of the variable in your .env file.

This indirection means you can use any variable names in your .env - useful when sharing an .env across multiple services with different naming conventions.

🔧 args - tool selection via tool= prefix

Each enabled MCP tool is declared as a separate arg using the tool=<name> format:

"args": [
  "-y",
  "@edelciomolina/postgres-mcp",
  "tool=pg_manage_schema",
  "tool=pg_manage_indexes"
]

This makes the tool list explicit and auditable directly in mcp.json - no hidden config files. 🔍

---

🛡️ Why read-only is the default

If you omit all tool= args, the server starts with a curated read-only set - every tool that can retrieve, analyze, or explain data, but nothing that can modify it.

⚠️ Excluded from defaults (write-capable, opt-in via tool= arg):

✅ Included in defaults:

pg_execute_query       pg_manage_query        pg_manage_schema
pg_manage_indexes      pg_manage_constraints  pg_manage_functions
pg_manage_triggers     pg_manage_rls          pg_get_setup_instructions
pg_manage_users        pg_analyze_database    pg_monitor_database
pg_debug_database

💡 pg_execute_query is included in the defaults but is handler-enforced read-only: the tool handler rejects any INSERT, UPDATE, DELETE, or DDL statement and returns a permission error before the database is contacted.

⚠️ Management tools like pg_manage_schema bundle both read and write sub-operations (e.g. get_info and create_table). For strict write prevention, pair with a database user that only has SELECT privileges.

💡 Tip: While this MCP is secure and customizable via tools, for maximum safety, pair the default tool set with a database user that only has SELECT privileges.

---

📍 .env file discovery

The server resolves the .env file in this order:

1. env-file=<path> arg - explicit path relative to cwd; takes priority over everything else
2. Walk-up - starting from cwd, searches each parent directory until a .env is found or the filesystem root is reached

If no .env is found, the server exits with a clear error message.

Monorepos and subfolders

When VS Code starts the MCP process, cwd is typically the workspace root. If your .env lives in a subfolder (e.g. functions/.env), use env-file= to point to it explicitly:

{
  "servers": {
    "Postgres Tools": {
      "type": "stdio",
      "command": "npx",
      "args": [
        "-y",
        "@edelciomolina/postgres-mcp",
        "env-file=functions/.env",
        "tool=pg_manage_schema",
        "tool=pg_monitor_database"
      ],
      "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"
      }
    }
  }
}

💡 The walk-up behavior handles the common case automatically. Use env-file= when you need explicit control (CI, monorepos, Docker bind-mounts).

---

🧰 Available tools

Read-only (enabled by default)

Write-capable (opt-in via tool= arg)

---

🏗️ Architecture

For a deep dive into the communication flow between the MCP client, proxy, and PostgreSQL - including the full sequence diagram - see ARCHITECT.md.

---

📄 License

MIT © Edelcio Molina