postgres-mcp-for-devs

A Model Context Protocol (MCP) server that connects your AI coding assistant to a Postgres database.

Unlike the official Postgres MCP server (read-only), this one supports full read/write SQL — SELECT, INSERT, UPDATE, DELETE, and even DDL like CREATE TABLE.

Previously published as pg-mcp-for-devs. Prefer this package going forward (npx -y postgres-mcp-for-devs).

Once configured, you can ask your AI things like:

• “List all tables in my database”
• “Show me the schema of users”
• “Insert a row into orders …”
• “Run this migration SQL”

The AI will call the tools exposed by this server instead of guessing.

What you need before starting

| Requirement | Notes | |-------------|--------| | Node.js 18+ | Required so npx can run the package. Check with node -v. | | A Postgres database | Local Docker, Homebrew Postgres, Neon, Supabase, RDS, etc. | | A connection string | Passed as DATABASE_URL (see below). | | An MCP-capable client | Cursor, Claude Code, GitHub Copilot (VS Code), or Windsurf. |

You do not need to clone this repo or run npm install yourself for normal use. The client will download and run the package via npx.

Step 1 — Get your DATABASE_URL

This server reads one environment variable:

DATABASE_URL

Format:

postgresql://USER:PASSWORD@HOST:PORT/DATABASE

Examples:

postgresql://postgres:postgres@localhost:5432/myapp
postgresql://user:[email protected]:5432/devdb
postgresql://user:[email protected]:5432/prod?sslmode=require

Tips:

• If your password has special characters (@, #, /, …), URL-encode them.
• Prefer a dedicated DB user with only the permissions you want the AI to have (especially if you allow writes).

Quick connectivity check (optional):

psql "$DATABASE_URL" -c 'select 1'

Step 2 — Add the MCP server to your client

Pick your client below. After saving the config, reload / restart MCP (or restart the app) so the new server is picked up.

Ready-made JSON files also live in examples/.

Cursor

Where to put the config

| Scope | Path | |-------|------| | This project only | <your-project>/.cursor/mcp.json | | All projects (global) | ~/.cursor/mcp.json |

What to put

{
  "mcpServers": {
    "postgres-mcp-for-devs": {
      "command": "npx",
      "args": ["-y", "postgres-mcp-for-devs"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Replace the DATABASE_URL value with yours.

Then

1. Save the file.
2. Open Cursor Settings → MCP and confirm postgres-mcp-for-devs appears and is enabled (green / connected).
3. If it fails, click refresh or restart Cursor, then check the server error log in that panel.

Example file: examples/cursor/mcp.json

Claude Code

Option A — Project config (good for teams)

1. Create (or edit) .mcp.json in your project root.
2. Paste:

{
  "mcpServers": {
    "postgres-mcp-for-devs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "postgres-mcp-for-devs"],
      "env": {
        "DATABASE_URL": "${DATABASE_URL}"
      }
    }
  }
}

3. Export the real URL in your shell before starting Claude Code:

export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"

Claude Code expands ${DATABASE_URL} from the environment, so you can commit .mcp.json without putting secrets in git.

Option B — CLI

export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
claude mcp add --scope project --env DATABASE_URL="$DATABASE_URL" -- npx -y postgres-mcp-for-devs

Then

1. Start a new Claude Code session in that project.
2. Run /mcp or claude mcp list and confirm the server is connected.

Example file: examples/claude-code/mcp.json

GitHub Copilot (VS Code)

Copilot / VS Code use a different JSON shape: the top-level key is servers, not mcpServers.

Where to put the config

| Scope | Path | |-------|------| | This workspace | <your-project>/.vscode/mcp.json | | User-wide | Command Palette → MCP: Open User Configuration |

What to put

{
  "inputs": [
    {
      "type": "promptString",
      "id": "database_url",
      "description": "Postgres connection string (DATABASE_URL)",
      "password": true
    }
  ],
  "servers": {
    "postgres-mcp-for-devs": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "postgres-mcp-for-devs"],
      "env": {
        "DATABASE_URL": "${input:database_url}"
      }
    }
  }
}

Then

1. Save .vscode/mcp.json.
2. Open the file — you should see a Start control for the server (or use Command Palette → MCP: List Servers).
3. Start the server. VS Code will prompt you for the connection string once.
4. Use Agent mode in Copilot Chat so tools can be invoked.

Example file: examples/copilot/mcp.json

Windsurf

Windsurf stores MCP config in a global file (not usually per-project):

| OS | Path | |----|------| | macOS / Linux | ~/.codeium/windsurf/mcp_config.json | | Windows | %USERPROFILE%\.codeium\windsurf\mcp_config.json |

What to put (merge into existing mcpServers if the file already has other servers):

{
  "mcpServers": {
    "postgres-mcp-for-devs": {
      "command": "npx",
      "args": ["-y", "postgres-mcp-for-devs"],
      "env": {
        "DATABASE_URL": "postgresql://user:password@localhost:5432/mydb"
      }
    }
  }
}

Then

1. Save the file.
2. Open Cascade → Manage MCPs → Refresh.
3. Confirm postgres-mcp-for-devs shows as connected.

You can also open the raw config from the Manage MCPs UI (“View raw config”).

Example file: examples/windsurf/mcp_config.json

Step 3 — Verify it works

In your AI chat, try:

1. “List all tables in my Postgres database.”
   → Should call list_tables and return names from the public schema.

2. “Describe the users table.” (use a real table name)
   → Should call describe_table and return columns / types.

3. “Run SELECT 1 AS ok.”
   → Should call execute_sql and return something like [{ "ok": 1 }].

If the model does not use tools, make sure MCP tools are enabled for that chat / agent mode, and that the server status is connected.

Available tools

| Tool | Arguments | What it does | |------|-----------|--------------| | list_tables | (none) | Lists all tables in the public schema. | | describe_table | table_name (string, required) | Returns column name, data type, nullability, default, and max length. | | execute_sql | query (string, required), params (array, optional) | Runs arbitrary SQL. Supports parameterized queries via params ($1, $2, …). |

execute_sql examples (what the AI may send)

{ "query": "SELECT id, email FROM users LIMIT 10" }

{
  "query": "INSERT INTO users (email) VALUES ($1) RETURNING *",
  "params": ["[email protected]"]
}

{ "query": "CREATE TABLE IF NOT EXISTS notes (id serial PRIMARY KEY, body text)" }

How it runs (mental model)

You ↔ Cursor / Claude Code / Copilot / Windsurf
        ↕  MCP over stdio
   npx postgres-mcp-for-devs
        ↕  DATABASE_URL
      Postgres

Your editor starts npx -y postgres-mcp-for-devs as a background process, passes DATABASE_URL, and talks to it over stdin/stdout. You normally never run the binary by hand.

Optional manual smoke test:

export DATABASE_URL="postgresql://user:password@localhost:5432/mydb"
npx -y postgres-mcp-for-devs

If it starts correctly you should see a message on stderr like Local Postgres MCP Server running.... Stop it with Ctrl+C. (Leaving it running in a terminal is not required for day-to-day use — the IDE manages the process.)

Troubleshooting

| Symptom | What to check | |---------|----------------| | Server missing / not listed | Config file path and JSON validity (trailing commas break JSON). Restart the client. | | Copilot ignores config | You used mcpServers instead of servers in .vscode/mcp.json. | | password authentication failed | Wrong user/password in DATABASE_URL. | | connection refused | Postgres not running, or wrong host/port. | | database "…" does not exist | Database name in the URL is wrong. | | SSL errors (cloud DBs) | Add ?sslmode=require (or the setting your provider documents). | | Tools error on every query | Confirm DATABASE_URL is actually set in the MCP env block (or prompted / exported for Claude Code). | | npx / Node not found | Install Node 18+ and ensure it is on your PATH for GUI apps (macOS GUI apps sometimes do not see shell PATH — restart the app after installing Node). | | AI won’t call tools | Enable agent / tool use; confirm the MCP server shows as connected. |

Security

• This server can read and write anything the DB user can. Do not point it at production unless you intend that.
• Prefer a least-privilege Postgres role (e.g. read-only if you only need exploration).
• Do not commit real passwords in shared config files. Use env vars (Claude Code ${DATABASE_URL}), VS Code ${input:…}, or a private global config.
• Treat chat transcripts as sensitive — query results may contain PII.

License

ISC