# Pg Readonly MCP

> Pg Readonly MCP is an open-source MCP server for databases. Read-only Postgres access for agents that parses SQL and refuses write-capable roles. It runs locally on your machine and is started by your AI client.

- **Kind:** MCP server
- **Pricing:** Open source
- **Platforms:** CLI, self-hosted
- **Website:** https://les-k.github.io/field-notes.html
- **Repository:** https://github.com/les-k/pg-readonly-mcp
- **MCP Registry name:** io.github.les-k/pg-readonly-mcp
- **Categories:** databases, security
- **Listing updated:** 2026-11-16

## About

This server was written in response to a published bypass in a reference Postgres server, where wrapping queries in a read-only transaction could be escaped with SELECT 1; COMMIT; DROP SCHEMA public CASCADE. Here the safety does not rest on transaction mode. Queries are parsed with sqlglot into a syntax tree and must be exactly one statement, have a read-shaped outer statement (SELECT, UNION, INTERSECT, EXCEPT or a CTE built from those), and contain no write anywhere in the tree, which catches data-modifying CTEs such as a DELETE inside a WITH. Unrecognised shapes are refused.

A second, independent layer checks the connection at startup. The server will not start if the role is a superuser, can create databases or roles, can bypass row-level security, or holds any grant beyond SELECT. The DSN comes from the PG_READONLY_MCP_DSN environment variable, which must point at a SELECT-only role.

The README lists what it does not cover: an over-privileged string that slips past the startup check, and costly but legal queries, which are bounded by row caps and a statement timeout. It runs over stdio from a PyPI package.

## Features

- **SQL parsed, not scanned:** Builds a syntax tree instead of pattern-matching text.
- **Single statement only:** Multi-statement payloads are refused before reaching the database.
- **Deep write detection:** Walks the whole tree to find writes hidden inside CTEs.
- **Startup privilege check:** Refuses roles with superuser, create or non-SELECT grants.
- **Row caps and timeout:** Limits the cost of legal but heavy queries.
- **Honest limits:** Documents what the guards cannot catch.

## Good for

- Let an agent explore a production schema safely
- Answer data questions with SELECT-only access
- Replace a read-only transaction approach with a parser-based guard
- Audit how a read-only MCP server is built

## Install

### Claude Code (Terminal)

```sh
claude mcp add pg-readonly-mcp --env PG_READONLY_MCP_DSN='<PG_READONLY_MCP_DSN>' -- uvx pg-readonly-mcp
```

### Claude Desktop (claude_desktop_config.json)

```json
{
  "mcpServers": {
    "pg-readonly-mcp": {
      "command": "uvx",
      "args": [
        "pg-readonly-mcp"
      ],
      "env": {
        "PG_READONLY_MCP_DSN": "<PG_READONLY_MCP_DSN>"
      }
    }
  }
}
```

### Cursor (~/.cursor/mcp.json)

```json
{
  "mcpServers": {
    "pg-readonly-mcp": {
      "command": "uvx",
      "args": [
        "pg-readonly-mcp"
      ],
      "env": {
        "PG_READONLY_MCP_DSN": "<PG_READONLY_MCP_DSN>"
      }
    }
  }
}
```

### VS Code (.vscode/mcp.json)

```json
{
  "servers": {
    "pg-readonly-mcp": {
      "type": "stdio",
      "command": "uvx",
      "args": [
        "pg-readonly-mcp"
      ],
      "env": {
        "PG_READONLY_MCP_DSN": "<PG_READONLY_MCP_DSN>"
      }
    }
  }
}
```

### Windsurf (~/.codeium/windsurf/mcp_config.json)

```json
{
  "mcpServers": {
    "pg-readonly-mcp": {
      "command": "uvx",
      "args": [
        "pg-readonly-mcp"
      ],
      "env": {
        "PG_READONLY_MCP_DSN": "<PG_READONLY_MCP_DSN>"
      }
    }
  }
}
```

### Other clients (your client's MCP settings (most use this shape))

```json
{
  "mcpServers": {
    "pg-readonly-mcp": {
      "command": "uvx",
      "args": [
        "pg-readonly-mcp"
      ],
      "env": {
        "PG_READONLY_MCP_DSN": "<PG_READONLY_MCP_DSN>"
      }
    }
  }
}
```

## FAQ

### What does it need to start?

A PG_READONLY_MCP_DSN connection string for a role that holds only SELECT.

### Why not just use a read-only transaction?

The README shows a COMMIT inside a multi-statement query can end that transaction early.

### Can it catch writes inside a CTE?

Yes, it walks every node of the parsed tree.

### Is the privilege check complete?

No, the README says ownership, PUBLIC grants and RLS policies are not fully enumerated.

### Is Pg Readonly MCP free?

Yes. Pg Readonly MCP is open source, so you can use and self-host it for free.

### How do I add Pg Readonly MCP to Claude Code?

Run this command in your terminal: claude mcp add pg-readonly-mcp --env PG_READONLY_MCP_DSN='<PG_READONLY_MCP_DSN>' -- uvx pg-readonly-mcp

### What are the best alternatives to Pg Readonly MCP?

The closest alternatives to Pg Readonly MCP are REA, Agent Roast, Midplane, Leash and Tinplate Edge AI Safety, Security & EU Compliance.

## Alternatives

- [REA](https://ai-powered.com/mcp/rea): REA is an open-source MCP server for developer tools.
- [Agent Roast](https://ai-powered.com/mcp/agent-roast): Agent Roast is an open-source MCP server for developer tools.
- [Midplane](https://ai-powered.com/mcp/midplane): Midplane is an open-source MCP server for databases.
- [Leash](https://ai-powered.com/mcp/leash): Leash is a free MCP server for security.
- [Tinplate Edge AI Safety, Security & EU Compliance](https://ai-powered.com/mcp/tinplate-edge-ai-safety-security-and-eu-compliance): Tinplate Edge AI Safety, Security & EU Compliance is a freemium MCP server for security.
- [SecureCloud](https://ai-powered.com/mcp/securecloud): SecureCloud is a free MCP server for security.
- [Eikino](https://ai-powered.com/mcp/eikino): Eikino is a freemium MCP server for security.
- [SynomosAI Governance MCP](https://ai-powered.com/mcp/synomosai-governance-mcp-2): SynomosAI Governance MCP is an open-source MCP server for security.

---
Source: https://ai-powered.com/mcp/pg-readonly-mcp
