# Postgres (read-only) [Health: Active]

**Category:** 🗄️ Databases  
**Repository:** https://github.com/contextflo/postgres-mcp  
**GitHub Stars:** 4  
**npm Downloads (last month):** 1008  
**Views:** 2  
**Installs:** 0  
**Upvotes:** 0  
**Directory Page:** https://allmcps.com/mcp/postgres-read-only

## Description
Read-only Postgres: drop-in for the archived server-postgres, with schema context.

## Tools
Capabilities this server exposes over MCP:

- **query** — Runs one read-only statement: `SELECT`, `WITH ... SELECT`, `EXPLAIN`, or `SHOW`.
- **list_tables** — Lists readable tables with descriptions. `pattern` matches anywhere in the name or description.
- **get_table_context** — Describes tables: columns, types, keys, foreign key targets, enum values, curated descriptions.
- **add_table_context** — Lets the agent write down a gotcha it found (`amount` is in cents, `status` has an undocumented value) in the context file.

## Claude Desktop Quick Installation
Install path detected from listing signals. Uses `npx` (confidence: high):

```json
"mcpServers": {
  "postgres-read-only": {
    "command": "npx",
    "args": ["-y","@contextflo/postgres-mcp"],
    "env": {
      "DATABASE_URL": ""
    }
  }
}
```

**Requires environment variables:** `DATABASE_URL` — the values above are empty placeholders; fill in real credentials before running (see the repository for what each one is for).

## Documentation

## What Postgres (read-only) MCP server does

Postgres (read-only) MCP server exposes PostgreSQL data and schema information to MCP clients for analytics and investigation tasks. Agents can run permitted read-only SQL, find readable tables, inspect their structure, and record notes about details that are not represented in the database schema.

The server is designed as a replacement for the archived `@modelcontextprotocol/server-postgres` package. Its read-only behavior is reinforced through the PostgreSQL protocol, connection settings, SQL parsing, and database permissions rather than relying on a single string check.

## How it works

The `query` tool accepts one statement from the supported read-only categories: `SELECT`, `WITH ... SELECT`, `EXPLAIN`, or `SHOW`. Statements run through PostgreSQL's extended query protocol inside an explicit read-only transaction that is rolled back after execution.

Before execution, the SQL is parsed with a PostgreSQL parser compiled to WebAssembly. The server walks the complete parse tree, including nested data-modifying expressions, and rejects unsupported or unknown constructs. Function calls are checked against PostgreSQL metadata; volatile functions and security-definer functions are generally refused, with a small allowlist for harmless functions needed by analysis.

A database role without write permissions provides an additional enforcement layer. This matters because read-only access limits what the connected identity can change, but it does not limit which permitted data the agent can read. The README also recommends using a replica or branch where possible because read-only queries can still consume substantial database resources.

The context file is shared between the team and the agent. It is seeded from table comments by the `init` command, can be edited manually, and can receive notes through `add_table_context`. Table schema resources using `postgres://<host>/<table>/schema` are also exposed for clients that use MCP resources.

## Setup and configuration

Create a PostgreSQL login role with `CONNECT` on the database, `USAGE` on the relevant schemas, and `SELECT` on the tables the agent should access. Grant default `SELECT` privileges if new tables should be visible automatically. The server warns when it connects as a superuser, and initialization reports if the connected role can write.

Set `DATABASE_URL` in a `.env` file in the directory where the server starts. The connection string can include provider options such as SSL settings. Start the package with `npx @contextflo/postgres-mcp postgresql://localhost/mydb`, or configure the client to run `npx -y @contextflo/postgres-mcp` while supplying the environment variable.

Run `npx @contextflo/postgres-mcp init` to create `.contextflo/context.md`. Use `--context-file` when the client starts outside the project directory. A 30-second statement timeout is available by default and can be changed with `--statement-timeout`; a row cap also limits returned results.

## Tools and capabilities

- `query` runs one permitted read-only SQL statement.
- `list_tables` returns readable tables and descriptions; `pattern` searches table names and descriptions.
- `get_table_context` returns columns, types, keys, foreign-key targets, enum values, and curated descriptions.
- `add_table_context` appends an agent-discovered note to the context file.
- SQL against `information_schema` and `pg_catalog` can provide more specialized discovery without a separate search tool.

## Limitations and notes

The Postgres (read-only) MCP server does not include a dedicated search tool. Agents must write SQL for searches such as locating columns by name. Read-only enforcement does not prevent expensive full-table scans or joins, so a replica or branch is preferable when available.

A user-defined function mislabeled as `STABLE`, or a side effect reached indirectly through a view, operator, or cast, may not be identified by the function checks. The read-only database role remains the recommended protection. Anything readable by that role is potentially readable by the agent.

_Full upstream README: https://allmcps.com/mcp/postgres-read-only/readme_

