@fauzitech/mcp-postgres

A safe, read-only-by-default Model Context Protocol (MCP) server for PostgreSQL. Let AI agents like Claude, Cursor, and Windsurf inspect and query your database — without the risk of an accidental DROP TABLE.

Why

Connecting an AI agent directly to your database is powerful — it can explore schemas, write queries, and debug data for you. But handing an LLM write access to production is asking for trouble. One hallucinated DELETE and you're restoring from backups.

mcp-postgres is read-only by default and enforces it at two layers:

1. SQL guard — parses each statement, strips comments and string literals, and rejects anything that isn't a pure read (SELECT, WITH, EXPLAIN, SHOW, …). It catches evasion tricks like data-modifying CTEs (WITH x AS (INSERT …)) and stacked statements.
2. READ ONLY transaction — every query runs inside BEGIN TRANSACTION READ ONLY, so even if the guard were bypassed, PostgreSQL itself refuses the write.

Writes are only ever possible if you explicitly start the server with --write.

Features

• Read-only by default — two-layer enforcement (SQL guard + read-only transaction)
• Schema introspection — list schemas, tables, and describe columns
• Safe query execution — statement timeout, row cap, single-statement enforcement
• Write mode — opt in explicitly with --write when you actually need it
• Zero config — point it at a connection string and go
• Tiny — one dependency tree, stdio transport, works anywhere Node runs

Installation

No install needed — run it straight with npx:

npx @fauzitech/mcp-postgres "postgresql://user:pass@host:5432/dbname"

Or install globally:

npm install -g @fauzitech/mcp-postgres
mcp-postgres "postgresql://user:pass@host:5432/dbname"

Usage with Claude Desktop

Add to your claude_desktop_config.json:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": [
        "-y",
        "@fauzitech/mcp-postgres",
        "postgresql://user:pass@host:5432/dbname"
      ]
    }
  }
}

Usage with Cursor

Add to .cursor/mcp.json in your project:

{
  "mcpServers": {
    "postgres": {
      "command": "npx",
      "args": ["-y", "@fauzitech/mcp-postgres", "postgresql://user:pass@host:5432/dbname"]
    }
  }
}

Usage with Hermes Agent

Add to ~/.hermes/config.yaml:

mcp_servers:
  postgres:
    command: "npx"
    args: ["-y", "@fauzitech/mcp-postgres"]
    env:
      DATABASE_URL: "postgresql://user:pass@host:5432/dbname"

Configuration

The connection string can be passed as the first argument or via the DATABASE_URL environment variable.

| Flag | Default | Description | |------|---------|-------------| | --write | off | Allow data-modifying statements (INSERT, UPDATE, DELETE, DDL). Use with caution. | | --allow-multiple | off | Allow multiple ;-separated statements per query call | | --max-rows=N | 1000 | Maximum rows returned by a single query | | --statement-timeout=MS | 15000 | Per-statement timeout in milliseconds |

Example — write mode with a higher row cap:

mcp-postgres --write --max-rows=5000 "postgresql://..."

Tools

The server exposes four tools:

query

Execute a SQL query. In read-only mode (default), only read statements are allowed.

query(sql: string)

list_schemas

List all non-system schemas.

list_schemas()

list_tables

List tables and views in a schema.

list_tables(schema?: string = "public")

describe_table

Show columns, types, nullability, and defaults for a table.

describe_table(table: string, schema?: string = "public")

Security model

| Layer | Protection | |-------|-----------| | SQL guard | Rejects non-read statements before they reach the database. Comment- and string-aware, so SELECT 'drop table' is fine but DROP TABLE is blocked. | | CTE inspection | Blocks data-modifying CTEs like WITH x AS (INSERT … RETURNING *) SELECT * FROM x. | | Statement count | Rejects stacked statements (SELECT 1; DELETE …) unless --allow-multiple is set — and even then each statement is individually guarded. | | READ ONLY transaction | Every read query runs in BEGIN TRANSACTION READ ONLY. A database-level guarantee independent of the guard. | | Statement timeout | SET LOCAL statement_timeout prevents runaway queries. | | Row cap | Results are truncated to --max-rows to avoid flooding the agent's context. |

Note on credentials: the connection string contains your database password. Prefer passing it via the DATABASE_URL environment variable rather than as a command-line argument, since arguments can be visible in process listings. When configuring an MCP client, use a least-privilege database role — ideally one with only SELECT grants.

Development

git clone https://github.com/muhfauziazhar/mcp-postgres.git
cd mcp-postgres
npm install
npm run build
npm test                     # unit tests (guard logic)
DATABASE_URL=postgresql://... npm test   # + integration test

License

MIT © Muhammad Fauzi Azhar