A read-only MCP server for inspecting and querying PostgreSQL databases.
pg-mcp-live exposes PostgreSQL schema information, table metadata, sample rows, safe SELECT queries, and query plans through the Model Context Protocol.
The goal is simple: give MCP-compatible clients useful database context without giving them write access.
Read-only MCP server for PostgreSQL introspection, safe SELECT queries, and schema resources.
—
Features
PostgreSQL schema introspection
table and column metadata
primary key and foreign key detection
index metadata
unique and check constraint metadata
table size and row estimates
safe sample row previews
read-only SELECT query execution
PostgreSQL EXPLAIN plans
MCP tools and resources
Docker-based demo database
SQL guard tests
MCP tools
Tool
Description
ping
Checks whether the server is running
check_database_connection
Tests the PostgreSQL connection
check_feature_support
Reports which optional database features are installed
list_event_sources
Lists allowed tables and whether they emit live notifications
list_schemas
Lists exposed schemas
list_tables
Lists base tables in exposed schemas
describe_table
Returns table metadata
get_table_sample
Returns sample rows
run_select_query
Runs a guarded read-only SELECT query
explain_query
Returns a PostgreSQL EXPLAIN plan
summarize_relationships
Returns a compact foreign-key relationship map
wait_for_notification
Waits for the next PostgreSQL notification on a channel
get_recent_events
Returns recent table-change events from the event log
summarize_recent_activity
Summarizes recent table-change activity
tail_recent_events
Waits for the next matching live event and returns its event-log rows
{
"ok": false,
"summary": "Failed to list schemas.",
"error": {
"message": "..."
}
}
MCP resources
Resource
Description
postgres://schemas
Lists exposed schemas
postgres://schema/{schemaName}
Lists base tables in a schema
postgres://table/{schemaName}/{tableName}
Returns table metadata, indexes, constraints, and stats
Safety model
The server is read-only by design, but it is not a complete database sandbox.
User-provided SQL is checked before execution. The query engine blocks common write, admin, and destructive operations, including:
INSERT
UPDATE
DELETE
DROP
ALTER
TRUNCATE
CREATE
GRANT
REVOKE
COPY
EXECUTE
CALL
MERGE
VACUUM
REINDEX
REFRESH
LOCK
ANALYZE
SELECT INTO
multiple SQL statements
row-locking clauses such as FOR UPDATE
The server also uses:
read-only transactions
statement timeouts
maximum row limits
schema allowlists
restricted PostgreSQL search_path for query tools
identifier validation
safe table-name quoting
This project is still early. Do not treat it as a complete production security boundary yet.
In particular, the SQL guard is based on blocking common dangerous patterns before running a query inside a read-only transaction. It does not fully constrain which SELECT-callable database functions a role may access. Use a least-privileged PostgreSQL role and treat database permissions as the primary security boundary.
Requirements
Node.js 20+
npm
Docker
Docker Compose
Quickstart
Clone the repository:
git clone https://github.com/Dem1241/pg-mcp-live.git
cd pg-mcp-live
Install dependencies:
npm install
Create a local environment file:
cp .env.example .env
Start the demo PostgreSQL database:
docker compose -f examples/docker-compose.yml up -d
Run checks:
npm test
npm run typecheck
npm run build
npm run self-check
Start the MCP server:
npm run dev
The server uses stdio transport. When started directly, it will wait for an MCP client.
On startup it also prints a short diagnostics summary to stderr describing database connectivity and optional live-event feature support.
Self-check
Run:
npm run self-check
This verifies database connectivity and reports whether optional live-event features are installed. The command exits with status 0 when the core setup works, and prints warnings if optional live-event pieces are missing.
Ainda não há lista de ferramentas. Servidores remotos recebem uma após a primeira verificação de saúde.
Perguntas frequentes
Perguntas
Como instalo Pg MCP Live?
Copie nesta página a configuração stdio para Cursor, Claude Desktop, Claude Code ou VS Code. Ela usa a instalação do publicador, não um proxy do PlugMCP.
Pg MCP Live precisa de uma chave de API?
Este registro não lista nenhuma variável de ambiente obrigatória.
Qual transporte Pg MCP Live usa?
Pg MCP Live roda localmente via stdio.
Quando Pg MCP Live foi verificado pela última vez?
Última verificação: 2026-10-28. Read-only MCP server for PostgreSQL introspection, safe SELECT queries, and schema resources.