pg-readonly-mcp
Server Configuration
Describes the environment variables required to run the server.
| Name | Required | Description | Default |
|---|---|---|---|
| PG_DSN | Yes | libpq connection string or URL. Use a read-only role. Required. The server refuses to start when missing or empty. | |
| PG_MAX_ROWS | No | Row cap. A per-call max_rows can only lower it. | 200 |
| PG_AUDIT_LOG | No | JSONL audit file, appended to. | ./audit.jsonl |
| PG_ALLOWED_TABLES | Yes | Comma-separated schema.table names allowed for access, e.g. public.orders,sales.items. Required. The schema defaults to public. The server refuses to start when missing or empty. | |
| PG_MAX_RESULT_BYTES | No | Cap on the JSON-serialized result in bytes. | 1000000 |
| PG_CONNECT_TIMEOUT_S | No | Connect timeout in seconds. | 5 |
| PG_STATEMENT_TIMEOUT_MS | No | SET LOCAL statement_timeout for every statement, in milliseconds. | 5000 |
Instructions
Guidance the server publishes about itself, which clients place ahead of the tool catalog so the model reads it before choosing anything.
Read-only access to an allow-listed set of PostgreSQL tables. Call list_tables first, describe_table for the ones you need, then query with a single SELECT. Writes, multiple statements and tables outside the allow-list are refused. Results are capped.
Capabilities
Features and capabilities supported by this server
Protocol revision2025-11-25
| Capability | Details |
|---|---|
| tools | {
"listChanged": false
} |
| prompts | {
"listChanged": false
} |
| resources | {
"subscribe": false,
"listChanged": false
} |
| experimental | {} |
Tools
Functions exposed to the LLM to take actions
| Name | Description |
|---|---|
| list_tablesA | List the tables this server may read (schema.table), with a row-count estimate and comment. |
| describe_tableA | Describe an allow-listed table: columns (name, type, nullable, default), primary key, indexes. |
| queryA | Run ONE read-only SELECT against allow-listed tables. Returns {columns, rows, row_count, truncated, duration_ms}. max_rows can only lower the server cap. |
Prompts
Interactive templates invoked by user choice
| Name | Description |
|---|---|
No prompts | |
Resources
Contextual data attached and managed by the client
| Name | Description |
|---|---|
No resources | |
TDQS
Scored across 3 tools
Each tool occupies a distinct stage of the workflow: list_tables for discovery, describe_table for schema introspection, and query for execution. The descriptions make the boundaries explicit (query only runs against allow-listed tables), so an agent cannot easily misselect.
list_tables and describe_table follow a clean verb_noun snake_case pattern, while 'query' is a bare verb that breaks the pattern slightly. It is still unambiguous and readable, so this is a minor deviation rather than an inconsistency.
Three tools map exactly onto the minimal complete set for a read-only SQL server: discover, inspect, execute. Nothing is redundant and no obvious capability is missing from the surface.
The read-only lifecycle is well covered, with truncation and max_rows controls, but describe_table omits foreign-key relationships and there is no way to page past the row cap beyond lowering it. These are minor gaps an agent can work around.