Postgres MCP: DATABASE_URL is not set (env var not inherited by the client)

Not specified by the original author.

TL;DR: Your shell knows DATABASEURL but the MCP server does not, because MCP clients launch servers with a clean environment. Put DATABASEURL directly in the env block of your client config (.mcp.json, claude_desktop_config.json), not just in your shell profile. Restart the client and the error is gone.

DATABASE_URL is not set

Fix it

1. Open your MCP client config. For Claude Desktop: claude_desktop_config.json. For Claude Code / Cursor: .mcp.json in the project root.
2. Add the variable to the server's env block:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@modelcontextprotocol/server-postgres", "YOUR_CONNECTION_URL"],
      "env": {
        "DATABASE_URL": "postgresql://db-host:5432/mydb"
      }
    }
  }
}

Note: several Postgres MCP servers read the URL from the first CLI arg instead of DATABASE_URL. If yours does, make sure the arg and the env var agree.

3. Fully quit and restart the client (not just the chat window). MCP servers are spawned at client launch.

   Expected: the server starts and tools like query appear. No startup error in the client logs.

When to use this

• echo $DATABASE_URL works in your terminal but the MCP server still says it is not set.
• You are on Windows, where env vars set in bash or PowerShell profiles are not inherited by servers launched via cmd.

When NOT to use this

• The error is password authentication failed or mentions SSL. The variable is being read fine; the credentials or TLS are the problem.
• The server reads the URL from a CLI argument rather than the environment. Then the arg is what matters.

Compatibility

• MCP Postgres servers that read DATABASE_URL at startup: yawlabs/postgres-mcp, Tabulus, pgedge-postgres-mcp.
• Claude Desktop, Claude Code, Cursor, Windsurf.

Why it happens

MCP servers are child processes of the client, and many clients (especially GUI apps on Windows and macOS) do not inherit your interactive shell environment. Variables exported in .bashrc or a terminal session simply do not exist in the server's process. The client config env block is the only reliable channel.

Edge cases

• JSON escaping: passwords with quotes or backslashes in the config file need JSON escaping. Prefer percent-encoding special chars.
• If you manage config with a dotfiles repo, remember the client reads its own config path, not your repo copy.
• Some servers validate DATABASE_URL at startup but only connect on the first tool call. A startup success does not prove the credentials work. Run a real query to be sure.

The yawlabs/postgres-mcp README troubleshooting documents DATABASEURL is not set with the explicit cause: the MCP client launches the server without the env var, and on Windows env vars set in bash or PowerShell profiles are not inherited by MCP servers launched via cmd. The documented fix is to put DATABASEURL directly in the env block of .mcp.json. The Tabulus troubleshooting table lists the same symptom (tabulus: DATABASEURL is required) with the same fix: set DATABASEURL in the .mcp.json / client env block, not just the shell. Source: https://github.com/yawlabs/postgres-mcp and https://github.com/WalkingMountain/tabulus

Not specified by the original author.

TL;DR: Managed Postgres providers (Supabase, Neon, RDS) require TLS and your MCP server is connecting without it. Append ?sslmode=require to the connection URL in your client config. That is the whole fix.

Error: SSL connection is required. Please specify SSL options and retry.

Variant phrasings you may see: SSL is required, server requires encryption, no pg_hba.conf entry for host ... SSL off.

Fix it

1. Find the connection URL in your MCP client config (env block, e.g. DATABASE_URL or the server's first CLI arg).
2. Append the SSL mode parameter:

postgresql://db.supabase.co:5432/postgres?sslmode=require

If the URL already has query parameters, join with & instead: ...?connect_timeout=10&sslmode=require.

3. Restart the MCP client so the server picks up the new URL.

   Expected: the next tool call connects and returns rows. No SSL error.

When to use this

• Connecting an MCP Postgres server to Supabase, Neon, RDS, or any managed Postgres.
• The error mentions SSL, TLS, or encryption being required.

When NOT to use this

• Local dev Postgres (Docker, Homebrew). Forcing SSL there causes the opposite error. Use sslmode=disable for local dev if needed.
• The error is a certificate verification failure (self-signed certificate). That needs the CA cert or a different sslmode, not just require.

Compatibility

• All MCP Postgres servers that pass the URL to node-postgres/pg: @modelcontextprotocol/server-postgres, yawlabs/postgres-mcp, Tabulus, pgedge-postgres-mcp.
• Supabase, Neon, AWS RDS, Google Cloud SQL, Azure Database for PostgreSQL.

Why it happens

Managed Postgres fleets terminate plain connections as a security policy. The pg driver defaults to opportunistic SSL (prefer), which is not enough for providers that mandate it. sslmode=require tells the driver to always negotiate TLS, which is what the provider expects.

Edge cases

• Supabase pooler URLs (port 6543) also need sslmode=require.
• If you get a certificate error after adding it, your provider uses a custom CA. Either supply the CA (sslrootcert) or check the provider docs for their recommended sslmode.
• Some servers read the URL once at startup. A client restart is required, not just a new chat.

The Tabulus (WalkingMountain/tabulus) troubleshooting table documents this exact failure mode: Error ... SSL ... required with the cause managed Postgres (Supabase, Neon, RDS) requires TLS and the fix append ?sslmode=require to the URL. This is the documented gotcha for connecting MCP Postgres servers to managed providers. Source: https://github.com/WalkingMountain/tabulus

Not specified by the original author.

TL;DR: The DATABASE_URL value is not reaching the shell that runs Prisma. Export it or pass it into the CI job / container environment explicitly, then re-run your Prisma command. The variable almost always exists somewhere (your secret store); it just was never forwarded to the process that needs it.

error: Environment variable not found: DATABASE_URL.

Steps

1. Confirm the variable is missing in the failing environment:

   echo "${DATABASE_URL:+set}"

   Expected: empty output. If it prints set, your shell sees it and the real problem is elsewhere.

2. In CI (GitHub Actions and similar), forward the secret into the job:

   jobs:
     deploy:
       env:
         DATABASE_URL: ${{ secrets.DATABASE_URL }}

   Expected: the Prisma step in the next run no longer fails at the env check.

3. In Docker / compose, declare it where the Prisma command runs:

   services:
     app:
       environment:
         - DATABASE_URL=${DATABASE_URL}

   Expected: docker compose exec app npx prisma validate loads the config without the env error.

4. Re-run the original command (npx prisma migrate deploy, prisma generate, etc.). Expected: the env error is gone. A different error (bad password, unreachable host) means the variable now arrives but its value is wrong.

When to use

• The exact message is Environment variable not found: DATABASE_URL on validate, migrate, generate, or db push
• The failure appears in CI, Docker, or any environment other than your local machine

When not to use

• The message complains the URL must start with a protocol (P1012): that means the var exists but its value is malformed
• Local shell: if your own terminal lacks it, just export it or fix your .env loader instead of touching CI

Compatibility

Prisma CLI 4.x through 7.x. Any CI provider or container runtime.

Variant phrasing: Environment variable not found: DIRECT_URL

Same shape, different variable. Forward DIRECT_URL the same way.

Variant phrasing: error appears during prisma generate in a Docker build

Build-time args do not become runtime env automatically. Pass DATABASE_URL as a build arg and also as a runtime environment entry.

Why it happens

Prisma reads connection strings from env() in the config or from the process environment. Secrets stored in a CI provider or orchestrator are not injected into a job or container unless the pipeline config forwards them. So the variable can be perfectly configured in your dashboard and still invisible to the Prisma process.

Edge cases

• Prisma 7 with prisma.config.ts skips auto-loading .env; add the dotenv import or export the variable for real in that shell.
• Shell quoting: a value containing # or ! gets mangled by unquoted assignment; quote it.
• If the error persists after forwarding, check for a typo in the variable name (DATABASEURL vs DATABASEURLS).

A CI deployment failed at the Prisma step with 'Environment variable not found: DATABASEURL.' even though the value was set in the CI provider's secret store. The cause was that the workflow never passed the secret into the job environment, so the Prisma CLI never saw it. The fix that worked: pass DATABASEURL explicitly into the CI job environment from the secret, so every Prisma command (validate, migrate deploy, generate) inherits it. After that change the pipeline went green. Source: https://github.com/shiblesadik603/ride-sharing-backend/commit/dfb579623d6248dd67f3c2300f9d88dfcdb0328c