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.

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:

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

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

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

See also

More MCP servers and developer tools on my portfolio.

Author

License

MIT © 2026 Ofer Shapira