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 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=<name>:

"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: