Postgres MCP

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= 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 Servers" (or "From registry", depending on your VS Code version)
4. Search for `postgres-mcp` or `edelciomolina`
5. Select Postgres MCP and follow the instructions - VS Code will add the entry to your mcp.json automatically

💡 You can also open the MCP Servers panel via 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= arguments and env key mappings as shown in the Usage section below.

---

🚀 Usage in VS Code (mcp.json)

Read-only (default - no `tool=` arguments needed):

{

"servers": { "Postgres Tools": { "type": "stdio", "command": "npx", "args": ["@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" } } } }

With write tools (explicit opt-in required):

{

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

⚠️ Write-capable tools require POSTGRES_MCP_ALLOW_WRITE=true in env. Without it, the server exits at startup.

The corresponding .env file at the root of your project:

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 variable name in your .env file.

Priority: when MCP_KEY_URL (or DATABASE_URL) is present, the server uses the URL directly and ignores the individual credential keys.

This indirection lets you use any variable name in your .env - useful when sharing a .env across multiple services with different naming conventions.

🔧 args - tool selection via tool= prefix

Each enabled MCP tool is declared as a separate argument in the format tool= :

"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 configuration files. 🔍

---

🔗 Connection via URL (DATABASE_URL)

In addition to individual credentials, you can provide a full connection string - the standard format on platforms like Supabase, Neon, and Railway.

`.env`:

DATABASE_URL=postgresql://user:password@host:5432/database?sslmode=require

`mcp.json`:

{

"servers": { "Postgres Tools": { "type": "stdio", "command": "npx", "args": ["-y", "@edelciomolina/postgres-mcp"], "env": { "MCP_KEY_URL": "DATABASE_URL" } } } }

The variable mapped by MCP_KEY_URL has priority over the other keys (MCP_KEY_HOST, MCP_KEY_PORT, etc.). If the URL is present, the other variables are ignored.

If the platform uses a different name (e.g. DB_URL), just adjust the mapping:

"MCP_KEY_URL": "DB_URL"

---

🛡️ Why read-only is the default

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

✅ Included in defaults (read-only):

pg_execute_query       pg_manage_query        pg_inspect_schema

pg_get_setup_instructions pg_analyze_database pg_monitor_database pg_debug_database pg_inspect_database_graph pg_describe_table_semantics pg_find_related_tables pg_classify_query_risk

💡 pg_execute_query rejects INSERT, UPDATE, DELETE, DDL, ANALYZE, VACUUM, EXPLAIN ANALYZE and other write/maintenance commands before the database is queried.

💡 pg_inspect_schema provides read-only schema introspection (get_info, get_enums). For DDL operations, use pg_manage_schema with explicit opt-in.

⚠️ Excluded from defaults - require `tool=` argument AND `POSTGRES_MCP_ALLOW_WRITE=true`:

---

📍 .env file discovery

The server resolves the .env file in this order:

1. `env-file= ` argument - explicit path relative to cwd; takes priority over everything
2. Upward search - 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 is 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" ], "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 upward search 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)

| pg_debug_database | Diagnose connections, locks, performance, a