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

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, without storing secrets in mcp.json
• 🗝️ Flexible key mapping - use any variable names in .env; tell the server which ones to use via env in mcp.json
• 🎯 Explicit tool selection - pass tool=<name> arguments 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 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_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=<path> 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)

Write-capable (opt-in via tool= argument + POSTGRES_MCP_ALLOW_WRITE=true)

🏗️ Architecture

For a detailed view of the communication flow between the MCP client, the proxy, and PostgreSQL - including the full sequence diagram - see ARCHITECT.md.

📄 License

MIT © Edelcio Molina

2025-09-08 update: The registry has launched in preview 🎉 (announcement blog post). While the system is now more stable, this is still a preview release and breaking changes or data resets may occur. A general availability (GA) release will follow later. We'd love your feedback in GitHub discussions or in the #registry-dev Discord (joining details here).

Current key maintainers:

• Adam Jones (Anthropic) @domdomegg
• Tadas Antanavicius (PulseMCP) @tadasant
• Toby Padilla (GitHub) @toby
• Radoslav (Rado) Dimitrov (Stacklok) @rdimitrov

Contributing

We use multiple channels for collaboration - see modelcontextprotocol.io/community/communication.

Often (but not always) ideas flow through this pipeline:

• Discord - Real-time community discussions
• Discussions - Propose and discuss product/technical requirements
• Issues - Track well-scoped technical work
• Pull Requests - Contribute work towards issues

Quick start:

Pre-requisites

• Docker
• Go 1.24.x
• ko - Container image builder for Go (installation instructions)
• golangci-lint v2.4.0

Running the server

# Start full development environment
make dev-compose

This starts the registry at localhost:8080 with PostgreSQL. The database uses ephemeral storage and is reset each time you restart the containers, ensuring a clean state for development and testing.

Note: The registry uses ko to build container images. The make dev-compose command automatically builds the registry image with ko and loads it into your local Docker daemon before starting the services.

By default, the registry seeds from the production API with a filtered subset of servers (to keep startup fast). This ensures your local environment mirrors production behavior and all seed data passes validation. For offline development you can seed from a file without validation with MCP_REGISTRY_SEED_FROM=data/seed.json MCP_REGISTRY_ENABLE_REGISTRY_VALIDATION=false make dev-compose.

The setup can be configured with environment variables in docker-compose.yml - see .env.example for a reference.

# Run latest stable release
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:latest

# Run latest from main branch (continuous deployment)
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main

# Run specific release version
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:v1.0.0

# Run development build from main branch
docker run -p 8080:8080 ghcr.io/modelcontextprotocol/registry:main-20250906-abc123d

Publishing a server

To publish a server, we've built a simple CLI. You can use it with:

# Build the latest CLI
make publisher

# Use it!
./bin/mcp-publisher --help

See the publisher guide for more details.

Other commands

# Run lint, unit tests and integration tests
make check

There are also a few more helpful commands for development. Run make help to learn more, or look in Makefile.

Architecture

Project Structure

├── cmd/                     # Application entry points
│   └── publisher/           # Server publishing tool
├── data/                    # Seed data
├── deploy/                  # Deployment configuration (Pulumi)
├── docs/                    # Documentation
├── internal/                # Private application code
│   ├── api/                 # HTTP handlers and routing
│   ├── auth/                # Authentication (GitHub OAuth, JWT, namespace blocking)
│   ├── config/              # Configuration management
│   ├── database/            # Data persistence (PostgreSQL)
│   ├── service/             # Business logic
│   ├── telemetry/           # Metrics and monitoring
│   └── validators/          # Input validation
├── pkg/                     # Public packages
│   ├── api/                 # API types and structures
│   │   └── v0/              # Version 0 API types
│   └── model/               # Data models for server.json
├── scripts/                 # Development and testing scripts
├── tests/                   # Integration tests
└── tools/                   # CLI tools and utilities
    └── validate-*.sh        # Schema validation tools

Authentication

Publishing supports multiple authentication methods:

• GitHub OAuth - For publishing by logging into GitHub
• GitHub OIDC - For publishing from GitHub Actions
• DNS verification - For proving ownership of a domain and its subdomains
• HTTP verification - For proving ownership of a domain

The registry validates namespace ownership when publishing. E.g. to publish...:

• io.github.domdomegg/my-cool-mcp you must login to GitHub as domdomegg, or be in a GitHub Action on domdomegg's repos
• me.adamjones/my-cool-mcp you must prove ownership of adamjones.me via DNS or HTTP challenge

Community Projects

Check out community projects to explore notable registry-related work created by the community.

More documentation

See the documentation for more details if your question has not been answered here!