mcp-server-postgres

Query PostgreSQL, inspect schemas, and explain queries from your AI assistant. A daily-driver MCP for local and dev Postgres — same belt as docker and sqlite servers, not an enterprise DBA suite.

bash

DATABASE_URL=postgres://user:pass@localhost:5432/mydb npx mcp-pg-server

Works with Claude Desktop, Cursor, VS Code Copilot, and any MCP client. Connects via DATABASE_URL or per-call connectionString.

Why

Postgres is the default for most new backends, local dev stacks, and agent workflows that need a real SQL database. You already run it in Docker or on localhost — this server lets your assistant query it, read schemas, and explain plans without leaving the IDE. Read-only by default so exploration stays safe; opt into writes when you need them.

Tools

Tool	What it does
`query`	Execute SQL (SELECT, WITH, EXPLAIN, SHOW, ANALYZE). Returns a text table.
`schema`	Tables in a schema (default `public`) with columns and approximate row counts
`table_info`	One table: columns, types, null/default, PK, exact row count
`explain`	EXPLAIN (FORMAT TEXT), optional ANALYZE
`list_schemas`	List non-system schemas

Quick Start

Cursor

Add to .cursor/mcp.json:

config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["mcp-pg-server"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Claude Desktop

Add to claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json):

config.json

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["mcp-pg-server"],
      "env": {
        "DATABASE_URL": "postgres://user:pass@localhost:5432/mydb"
      }
    }
  }
}

VS Code

Configure the MCP server in your VS Code settings to run npx mcp-pg-server with DATABASE_URL set.

Example prompts

"Show me the schema of the public tables"
"Query users: SELECT * FROM users LIMIT 10"
"Explain this join query"
"What schemas exist in this database?"
"How many rows are in the orders table?"

Safety

Read-only by default. The query tool accepts only SELECT, WITH, EXPLAIN, SHOW, and ANALYZE in readonly mode. Set readonly=false to enable INSERT, UPDATE, DELETE, and DDL.

Pass connectionString on any tool to override DATABASE_URL for a single call.

Development

Terminal

npm install
npm run typecheck
npm run build
npm test
npm run format
npm run lint

Postgres README