MCP 服务器

postgresql-mcp

A general-purpose PostgreSQL MCP server with full read-write SQL access, atomic multi-statement transactions, and schema inspection. Works with any PostgreSQL instance — local, Supabase, AWS RDS, or self-hosted — and connects to Claude, Cursor, Windsurf, or any MCP-compatible AI client.

README

postgresql-mcp

A Model Context Protocol (MCP) server for PostgreSQL with full read-write support, atomic transactions, and schema inspection. Works with Claude Desktop, Cursor, Windsurf, and any MCP-compatible AI client.

Connect any PostgreSQL database — local, Supabase, AWS RDS, or self-hosted — to your AI assistant in seconds.

Features

Full read-write SQL access (SELECT, INSERT, UPDATE, DELETE, CREATE, DROP)
Atomic multi-statement transactions with automatic rollback on failure
Schema inspection: columns, types, nullability, defaults, primary keys
Optional read-only mode via ?mode=readonly
No cloud lock-in — works with any standard PostgreSQL connection string
Single file, minimal dependencies

Why this exists

There are two other PostgreSQL MCP servers worth knowing about, and neither fully covers the general-purpose use case:

Anthropic's official @modelcontextprotocol/server-postgres is strictly read-only — it exposes only a single query tool that runs inside a READ ONLY transaction. No writes, no DDL, no transactions. It was also deprecated and archived in July 2025.

Microsoft's azure-postgresql-mcp does support writes and DDL, but it is built specifically for Azure Database for PostgreSQL Flexible Server. While it technically accepts standard PG* environment variables (so a local connection may work), local use is untested and unsupported. Several tools require Microsoft Entra authentication and Azure-specific APIs that won't function outside Azure. It also pulls in Azure SDK dependencies you don't need for a non-Azure setup. It is currently in Preview.

This server is the alternative for everything else: local PostgreSQL, self-hosted, Supabase, RDS, or any standard PostgreSQL instance. It is a single dependency-light file with no cloud lock-in, full read-write support, atomic multi-statement transactions, and an optional ?mode=readonly flag when you want to restrict access.

Requirements

Node.js 18+
A running PostgreSQL database

Installation

npm install -g @sarmadparvez/postgresql-mcp

Or run directly without installing (requires npm 7+ / Node.js 18+):

npx @sarmadparvez/postgresql-mcp <postgresql-connection-string>

Usage

postgresql-mcp <postgresql-connection-string>

Examples:

# Read-write access
postgresql-mcp postgresql://user:pass@localhost:5432/mydb

# Read-only mode (disables execute and transaction tools)
postgresql-mcp postgresql://user:pass@localhost:5432/mydb?mode=readonly

Or with npx (requires npm 7+ / Node.js 18+):

npx @sarmadparvez/postgresql-mcp postgresql://user:pass@localhost:5432/mydb
npx @sarmadparvez/postgresql-mcp postgresql://user:pass@localhost:5432/mydb?mode=readonly

Tools

Tool	Available in	Description
`query`	Always	Execute a read-only `SELECT` query. Runs inside a `READ ONLY` transaction. Returns rows as JSON.
`execute`	Read-write mode	Execute a write SQL statement (`INSERT`, `UPDATE`, `DELETE`, `CREATE`, `DROP`, etc.). Returns rows affected.
`schema`	Always	List columns, types, nullability, defaults, and primary keys for tables in a given schema. Optionally filter to a specific table.
`list_tables`	Always	List all base tables in a schema with their disk size.
`transaction`	Read-write mode	Execute multiple SQL statements atomically. Rolls back all statements if any one fails.

Read-Only Mode

Append ?mode=readonly to the connection string to start the server in read-only mode. This disables the execute and transaction tools, leaving only query, schema, and list_tables.

Claude Desktop Configuration

First, install the package globally:

npm install -g @sarmadparvez/postgresql-mcp

Then find the paths to node and the installed script:

which node
# e.g. /usr/local/bin/node
# nvm users: /Users/yourname/.nvm/versions/node/v22.12.0/bin/node

npm root -g
# e.g. /usr/local/lib/node_modules
# nvm users: /Users/yourname/.nvm/versions/node/v22.12.0/lib/node_modules

Add this to your claude_desktop_config.json:

Replace command with the output of which node
Replace the prefix of the script path with the output of npm root -g — the suffix /@sarmadparvez/postgresql-mcp/index.js stays the same

{
  "mcpServers": {
    "postgres": {
      "command": "/usr/local/bin/node",
      "args": [
        "/usr/local/lib/node_modules/@sarmadparvez/postgresql-mcp/index.js",
        "postgresql://user:pass@localhost:5432/mydb"
      ]
    }
  }
}

For read-only access, append ?mode=readonly to the connection string:

{
  "mcpServers": {
    "postgres-readonly": {
      "command": "/usr/local/bin/node",
      "args": [
        "/usr/local/lib/node_modules/@sarmadparvez/postgresql-mcp/index.js",
        "postgresql://user:pass@localhost:5432/mydb?mode=readonly"
      ]
    }
  }
}