postgres-mcp
Provides read-only access to PostgreSQL databases, with MCP tools for listing schemas and tables, describing table columns/types/indexes, and executing single SELECT/WITH queries under YAML-based schema, table, row, and timeout policies.
This server does not currently have a deployable release on Glama. Follow the repository's setup instructions to install and configure it for your MCP client, including any required credentials and local dependencies.
Overview
Give an agent read-only access to PostgreSQL without handing it the whole database. postgres-mcp speaks Model Context Protocol over HTTP, accepts a single YAML policy, and refuses to boot if that policy or its secrets are missing.
The PostgreSQL role is the primary boundary. YAML adds schema/table rules, row and time limits, and SQL validation on top.
Related MCP server: MCP Server for Database
Features
Read-only by default —
BEGIN READ ONLY, no write tools,security.readonlycannot be disabled in v0.1YAML policies — allow/deny schemas and tables, query limits, introspection toggles
Docker-ready — one container, env-based secrets, published as
recordari/postgres-mcpPrivate networking — bind to loopback, shared Docker networks, Tailscale Serve
Documentation
Guide | Description |
Disposable demo database + first query | |
Health check and smoke test | |
Existing PostgreSQL | |
Cursor / Streamable HTTP | |
What agents can call | |
Full YAML reference + JSON Schema | |
Production container layout | |
Private VM + HTTPS | |
Guarantees and limits | |
How to send changes | |
For AI agents editing this repo |
Quick Start
Demo only. This starts a throwaway PostgreSQL and builds the MCP server from source. You do not need an existing database or credentials.
Already have PostgreSQL? Skip to Connect your database.
git clone https://github.com/recordari/postgres-mcp.git
cd postgres-mcp
export MCP_TOKEN="$(openssl rand -hex 32)"
docker compose -f examples/docker-compose.yaml up --buildIn another terminal, verify and smoke-test:
curl -fsS http://127.0.0.1:3000/healthz
export MCP_TOKEN # same value as above
bash examples/smoke-test.sh http://127.0.0.1:3000Expected health response:
{"status":"ok"}Then connect your client (below) and ask: What tables are available in my database?
For a published image (no local build), see Docker deployment.
Verify your install
Step | Command | Success |
Health |
|
|
Logs |
| No config or auth errors |
MCP |
|
|
GET /healthz and GET /logo.png do not require authentication and return no database content. POST /mcp always requires Authorization: Bearer <MCP_TOKEN>.
Validate a config file before deploy:
export CONFIG_PATH=./config.yaml
export DATABASE_URL='postgres://...'
export MCP_TOKEN='...'
npm run config:validateConnect your database
Create a least-privilege role —
examples/sql/create_mcp_readonly_role.sql.Copy
examples/config.minimal.yamltoconfig.yamland adjustsecurity.access.Follow Docker deployment for networking and
docker run.
Production image (pin a version tag):
export DATABASE_URL='postgres://mcp_readonly:SECRET@postgres:5432/app'
export MCP_TOKEN="$(openssl rand -hex 32)"
docker run -d \
--name postgres-mcp \
--restart unless-stopped \
--network your-docker-network \
-p 127.0.0.1:3000:3000 \
-e DATABASE_URL \
-e MCP_TOKEN \
-v "$PWD/config.yaml:/app/config.yaml:ro" \
recordari/postgres-mcp:0.1.0Private HTTPS via Tailscale: docs/deployment/tailscale.md.
Connect your AI client
Streamable HTTP MCP clients need the /mcp URL and a bearer header. Example for Cursor — examples/cursor/mcp.json:
{
"mcpServers": {
"postgres": {
"url": "http://127.0.0.1:3000/mcp",
"headers": {
"Authorization": "Bearer YOUR_MCP_TOKEN"
}
}
}
}Replace the URL when using Tailscale or another reverse proxy. If you use a Tailscale hostname, add it to security.http.allowedHosts in config.yaml.
MCP tools
Tool | Purpose | Limits |
| Authorized schema names | No SQL; off when |
| Tables/views in one schema | Omits views that depend on denied relations |
| Columns, types, indexes | Policy-checked; no row samples |
| One |
|
v0.1 has no migrations, DML, tuning helpers, or multi-user tokens. Rotate MCP_TOKEN to revoke access.
Tool descriptions are also exposed to clients via MCP tools/list.
Configuration
See docs/configuration.md for every key, default, and placeholder rule. Editor autocomplete: docs/config.schema.json (regenerate with npm run config:schema; attached to each GitHub Release).
Minimal shape:
database:
url: ${DATABASE_URL}
security:
authentication:
type: bearer
token: ${MCP_TOKEN}
readonly: true
access:
schemas:
allow: [public]
queries:
maxRows: 1000
timeoutMs: 10000
singleStatement: trueOnly ${DATABASE_URL} and ${MCP_TOKEN} may appear in YAML. Unknown placeholders abort startup.
Security model
Three layers (outer layers never replace the database role):
PostgreSQL privileges — role can only
SELECTwhat you granted.Read-only execution —
BEGIN READ ONLY,statement_timeout, cursorFETCHcapped atmaxRows.Declarative YAML + SQL parser — relation allow/deny, conservative view expansion, denied functions and statement types.
View expansion via pg_depend is not a guarantee against every indirect data path—use approved views in a locked-down schema when data is sensitive. Details and disclosure: SECURITY.md.
Releases
Version lives in package.json. Tags must match before Docker Hub publish.
npm version patch -m "Release %s"
git push origin HEAD --follow-tagsImage tag | When |
| every release |
| every release |
| stable releases only |
CI needs DOCKERHUB_USERNAME and DOCKERHUB_TOKEN repository secrets.
Development
Node.js 22+. Agents editing the code should read AGENTS.md.
npm ci
npm test
npm run lint
DATABASE_URL=postgres://postgres:postgres@localhost:5432/app npm run test:integrationLicense
Apache License 2.0. Copyright 2026 Recordari.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
PostgreSQL, MySQL, and SQL Server in one session. 26 read-only MCP tools for AI agents.
Safe, read-only Postgres and MySQL access for AI agents. Audit log + column-level controls.
Guard AI agents' PostgreSQL/MySQL access via MCP: SQL audit, auth, masking, write approval
Deterministic safety, correctness & cost gate that vets Postgres SQL before your AI agent runs it.
Related MCP Servers
- AlicenseNot gradedqualityDmaintenanceA read-only PostgreSQL MCP server that enables AI agents to perform schema introspection and execute SELECT-only queries. It supports secure database connections through SSL and SSH tunnels while offering a structure-only mode to restrict query access.9 npmMIT
- FlicenseNot gradedqualityDmaintenanceA read-only MCP server that enables AI agents to explore database schemas and execute safe queries on PostgreSQL and MySQL.-
- AlicenseAqualityBmaintenanceA security-hardened Postgres MCP server that enables LLM agents to run safe, read-only SQL queries with enforcement via SQL-AST inspection and read-only transactions.1MIT
- AlicenseAqualityDmaintenanceA Postgres MCP server that enables AI agents to safely access production databases through deny-by-default YAML policies, PII masking, row limits, and required predicates. It also provides DBA capabilities like index tuning, health checks, and EXPLAIN plans, with support for multiple databases.10MIT