Pgmoat

pgmoat

[CI] [npm version] [License: MIT]

Governed Postgres access for AI agents.

pgmoat is an open-source MCP server that gives AI agents read-only access to Postgres. It checks every query with the real Postgres parser, hides the tables and columns you mark hidden, applies row limits and timeouts, binds Row-Level Security to the caller's identity, and writes a tamper-evident audit log.

Requires Node.js 22.12 or newer and Postgres 15 to 18.

Quickstart

Run it against your database with safe defaults, no config file needed:

npx -y pgmoat postgresql://readonly_user:password@localhost:5432/mydb

Add it to Claude Code:

claude mcp add pgmoat -- npx -y pgmoat postgresql://readonly_user:password@localhost:5432/mydb

Or to Claude Desktop (claude_desktop_config.json):

{  "mcpServers": {    "pgmoat": {      "command": "npx",      "args": ["-y", "pgmoat", "--url-env", "PGMOAT_DATABASE_URL"],      "env": { "PGMOAT_DATABASE_URL": "postgresql://readonly_user:password@localhost:5432/mydb" }    }  }}

Passing the URL through --url-env keeps the password out of process listings.

Use a dedicated read-only role. pgmoat checks the role at startup. With a pgmoat.yaml, it refuses to start if the role is a superuser (PGM-701), has BYPASSRLS while row-level security is configured (PGM-702), or owns a protected table without FORCE ROW LEVEL SECURITY (PGM-703), unless you pass --allow-unsafe-role; every audit entry then records the override. In zero-config mode (a URL and no config file) it warns and continues.

Add descriptions and hide sensitive data

export PGMOAT_DATABASE_URL=postgresql://readonly_user:password@localhost:5432/mydbnpx pgmoat init          # writes pgmoat.yaml; auto-hides columns like password_hash and token_hashnpx pgmoat validate      # checks the file against the schema and the databasenpx pgmoat doctor        # checks the role for unsafe privilegesnpx pgmoat start         # starts the server with ./pgmoat.yaml

A pgmoat.yaml looks like this:

version: 1server:  name: mydbconnection:  url: ${PGMOAT_DATABASE_URL}  schemas: [public]mode: read-onlybudgets:  max_rows: 200  max_query_ms: 5000tables:  users:    description: "One row per login account"    columns:      password_hash: { hidden: true }      email:         { sensitive: high }

Commands

Run pgmoat --help for all options.

What pgmoat does not do

• It does not stop prompt injection. It removes the write path, hides what you mark hidden, and labels returned data as untrusted, but an agent with other tools (web access, email) can still be tricked into sending readable data elsewhere.
• It does not replace Postgres permissions. The strongest control is a dedicated role with only the grants it needs.
• It does not make RLS policies correct. It sets the session variables your policies read. A flawed policy stays flawed.
• It does not guarantee audit delivery to a remote destination during an outage. It buffers, alarms, and records drops.

Docker

docker run -i --rm \  -e PGMOAT_DATABASE_URL="postgresql://readonly_user:[email protected]:5432/mydb" \  ghcr.io/kitalon-labs-llc/pgmoat:latest

Contributing

See CONTRIBUTING.md. Report vulnerabilities privately as described in SECURITY.md.

Links

• Docs: https://kitalonlabs.com/pgmoat/docs
• Source and issues: https://github.com/Kitalon-Labs-LLC/pgmoat
• Security reports: [email protected]

License

MIT (c) 2026 Kitalon Labs