MCPg MCP server

MCPg

A production-grade Model Context Protocol server for PostgreSQL. It lets AI agents safely inspect, query, operate, and tune a Postgres database — 279 tools spanning catalog introspection, query intelligence, natural-language SQL, structural diffs, hybrid search, graph queries, data movement, live ops, and more.

Try it live: point an MCP client — or the MCP Inspector — at the hosted, read-only demo endpoint https://devopam-mcpg-demo.hf.space/mcp. It serves read tools against throwaway demo data; for real use, run MCPg next to your own database (see Quick start).

📍 Listed On

• Official MCP Registry
• mcp.so
• mcpservers.org
• Glama
• MCP ServerList

---

Aspect	MCPg
Safety	Read-only default + AST validation
Transport	stdio + HTTP/SSE
Install	pip install mcpg
Postgres Versions	14–19
Key Differentiator	Production observability + multi-tenancy

Why MCPg

• Safe by default. Read-only access mode. Every user-supplied SQL statement parses through a validated AST allowlist before execution. Names that reach PostgreSQL as SQL identifiers are encoded with delimited-identifier quoting (see Identifier policy), not rejected merely for containing hyphens or other legal characters. Capabilities like DDL, shell, and LISTEN/NOTIFY are off until you opt in. Every tool publishes MCP ToolAnnotations (readOnlyHint, openWorldHint) derived from those same gates, so clients can auto-approve reads and gate writes without guessing.
• One server, broad surface. Application data access (queries, search, cursors, NL→SQL) and DBA-grade operations (health checks, index tuning, EXPLAIN analysis, locks, vacuum, dumps, replicas, migrations) in a single MCP server. Agents don't have to switch tools to switch tasks.
• PostgreSQL-native everything. No ORM, no abstraction tax — uses psycopg3 directly, speaks every pg_* system view, integrates with TimescaleDB, pgvector, PostGIS, Apache AGE, and pg_stat_statements where they're available, and degrades gracefully when they aren't.
• Production-shaped, not demo-shaped. Connection pooling, per-request SET ROLE multi-tenancy, read-replica routing with degraded-host detection, server-side cursors with dedicated connections, rate-limiting, audit trail with regex redaction, PG TLS enforcement on startup, OIDC JWT bearer auth, per-session statement / lock timeouts.
• Observability built in. Prometheus /metrics endpoint on the HTTP transport surfaces mcpg_tool_calls_total{tool,status} + mcpg_tool_duration_seconds. Every tool call records a structured audit event with credential-redacted arguments.
• Test-driven, multi-version. 2,500+ unit tests plus an integration suite that runs against a real PostgreSQL container in CI — matrix covers PG 14, 15, 16, 17, 18 on every push, plus PG 19 (beta) as an experimental (non-blocking) entry tracked under issue #120.

---

Install

From PyPI (recommended)

pip install mcpg
# or, in an isolated venv exposed globally:
uv tool install mcpg

Verify:

mcpg --version

Docker

Pull the pre-built image from the GitHub Container Registry (published on every tagged release — :latest tracks the newest, or pin a version like :0.6.5):

docker pull ghcr.io/devopam/mcpg:latest
docker run --rm --name mcpg -p 8000:8000 \
    -e MCPG_DATABASE_URL=postgresql://user:pass@host:5432/db \
    -e MCPG_ACCESS_MODE=read-only \
    ghcr.io/devopam/mcpg:latest

On Windows PowerShell replace the trailing \ with a backtick ` (or put the command on one line); the installation guide has ready-to-copy Linux/macOS, PowerShell, and Command Prompt blocks.

Or build it yourself from source:

docker build -t mcpg https://github.com/devopam/MCPg.git

Multi-stage image: runtime stage drops the build toolchain, runs as uid=10001 / gid=10001 with nologin shell, application files root-owned and read-only to the runtime user.

From source (developers)

git clone https://github.com/devopam/MCPg && cd MCPg
uv sync

uv sync creates a venv with all runtime + dev dependencies and exposes the mcpg console script.

More detail in the Installation Guide.

---

Quick start

One-click installs: — setup for Windsurf, JetBrains, Zed, Cline, Antigravity, Qwen Code, Perplexity, ChatGPT, Copilot Studio, Continue, and HTTP clients in the integrations guide.

One-click install in Claude Desktop (.mcpb)

Download mcpg-<version>.mcpb from the latest release and double-click it (or drag it into Claude Desktop's Settings → Extensions). You'll be prompted for your PostgreSQL connection URL — stored in the OS keychain — and an access mode (defaults to read-only). That's the whole install: the bundle is ~2 kB and the host resolves the pinned mcpg release from PyPI for your platform.

Or wire it up manually (stdio transport)

Drop this into your claude_desktop_config.json (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json; Windows: %APPDATA%\Claude\claude_desktop_config.json):

{
  "mcpServers": {
    "mcpg": {
      "command": "uvx",
      "args": ["mcpg"],
      "env": {
        "MCPG_DATABASE_URL": "postgresql://user:pass@localhost:5432/mydb"
      }
    }
  }
}

Restart Claude Desktop. The MCPg toolset is now available to the model. You can ask Claude things like:

"What schemas exist in this database? For each one, summarise the three biggest tables."

"Why is this query slow? SELECT * FROM orders WHERE customer_id = 42 ORDER BY created_at DESC"

No interesting data yet? Seed the demo dataset

MCPG_DATABASE_URL=postgresql://... mcpg --demo

One command seeds a small, curated e-commerce dataset (3,000 orders, 900 product reviews, deliberately planted flaws) into an mcpg_demo schema — engineered so the index advisor, query-plan analysis, full-text search, PII audit, and graph projection all have something real to find on your first try. See the guided tour for a captured walkthrough, and remove it any time with mcpg --demo-drop.

Run as an HTTP server (for IDE integrations, web apps, etc.)

MCPG_DATABASE_URL=postgresql://user:pass@localhost:5432/mydb \
MCPG_TRANSPORT=streamable-http \
MCPG_HTTP_PORT=8000 \
mcpg

Then point any MCP-aware client at http://localhost:8000/mcp (or /sse for the SSE transport). The HTTP transport refuses to start unless it's authenticated — set MCPG_HTTP_AUTH_TOKEN=... for a static bearer, or MCPG_AUTH_MODE=oidc for full JWT validation against an OIDC issuer. To deliberately run without auth (not recommended), set MCPG_HTTP_ALLOW_UNAUTHENTICATED=true.

---

Configuration

MCPg is configured entirely through environment variables — no config file, no flags (the CLI's --version / --demo / --demo-drop are one-shot commands, not configuration). The only required one is MCPG_DATABASE_URL; everything else has a safe default.

Common scenarios

Scenario	Set
Local exploration, read-only	MCPG_DATABASE_URL
Read-write app data access	MCPG_ACCESS_MODE=restricted
DBA toolkit (DDL, vacuum, etc.)	MCPG_ACCESS_MODE=unrestricted + MCPG_ALLOW_DDL=true
HTTP transport with bearer auth	MCPG_TRANSPORT=streamable-http + MCPG_HTTP_AUTH_TOKEN=…
Multi-tenant SaaS	MCPG_DEFAULT_ROLE=tenant_a + MCPG_ALLOWED_ROLES=tenant_a,tenant_b,…
Read-replica fan-out	MCPG_REPLICA_URLS=postgresql://…?sslmode=require,postgresql://…?sslmode=require
NL→SQL — single provider	Set any one vendor key (ANTHROPIC_API_KEY, OPENAI_API_KEY, GEMINI_API_KEY, XAI_API_KEY, GROQ_API_KEY, HF_TOKEN, … — 22 built-in providers). MCPg auto-picks the default.
NL→SQL — multiple providers, caller picks	Set all vendor keys you want active. Each call to translate_nl_to_sql can pass provider="…" (any configured built-in or custom).

Full reference

Core

Variable	Default	Description
MCPG_DATABASE_URL	required	Primary PostgreSQL DSN. Supports URI (postgresql://…) and keyword (host=… user=…) forms. Remote hosts require sslmode=require (or stronger).
MCPG_ACCESS_MODE	read-only	read-only | restricted (allows write tools) | unrestricted (also unlocks DBA tools when paired with the gate vars).
MCPG_TRANSPORT	stdio	stdio (default, for Claude Desktop) | streamable-http | sse.
MCPG_LOG_LEVEL	INFO	DEBUG | INFO | WARNING | ERROR | CRITICAL.
MCPG_HTTP_HOST	127.0.0.1	Bind address for HTTP transports. Set to 0.0.0.0 inside containers.
MCPG_HTTP_PORT	8000	Listen port for HTTP transports (1–65535).

Capability gates (opt-in for higher-blast-radius tools)

Variable	Default	Description
MCPG_ALLOW_DDL	false	Expose DDL tools (run_ddl, create_graph, drop_graph, hypertable tools, migration tools). Requires MCPG_ACCESS_MODE=unrestricted.
MCPG_ALLOW_SHELL	false	Expose subprocess-backed tools (dump_database, restore_database, run_pg_binary). Required PG client binaries must be on PATH.
MCPG_ALLOW_TIMESCALEDB_ADMIN	false	With unrestricted mode + MCPG_ALLOW_DDL, expose the destructive / heavy TimescaleDB tools (drop_chunks, compress_chunk, decompress_chunk, reorder_chunk, merge_chunks, refresh_continuous_aggregate, run_job, alter_job, delete_job); each needs dry_run then confirm=true + confirmation_token. See docs/timescaledb.md.
MCPG_ALLOW_ALTER_SYSTEM	false	Expose alter_system, alter_system_reset_all, reload_config (unrestricted mode only; two-step confirm=true flow — see docs/alter-system.md). MCPG_ALTER_SYSTEM_ALLOWLIST / MCPG_ALTER_SYSTEM_DENYLIST (comma-separated GUC names) narrow or extend the built-in denylist.
MCPG_ALLOW_LISTEN	false	Expose LISTEN/NOTIFY tools (subscribe_channel, poll_notifications, unsubscribe_channel, list_notification_subscriptions).

Authentication (HTTP transports only)

Variable	Default	Description
MCPG_AUTH_MODE	static	static (compare bearer to MCPG_HTTP_AUTH_TOKEN) | oidc (full JWT validation).
MCPG_HTTP_AUTH_TOKEN	—	Required bearer token when MCPG_AUTH_MODE=static. Constant-time compare. The HTTP transport refuses to start (ConfigError) unless this, MCPG_AUTH_MODE=oidc, or MCPG_HTTP_ALLOW_UNAUTHENTICATED=true is set.
MCPG_HTTP_ALLOW_UNAUTHENTICATED	false	Explicit opt-out of the HTTP transport's fail-closed auth check. Loudly logged on every startup when set; not recommended.
MCPG_OIDC_ISSUER	—	OIDC issuer URL (required when MCPG_AUTH_MODE=oidc).
MCPG_OIDC_AUDIENCE	—	Expected aud claim (required when MCPG_AUTH_MODE=oidc).
MCPG_OIDC_JWKS_URL	discovered	Override JWKS endpoint (auto-discovered from issuer's .well-known otherwise).
MCPG_OIDC_ROLE_CLAIM	—	JWT claim whose value becomes the per-request PG role (SET LOCAL ROLE). Composes with the tenancy driver.

HTTP hardening (HTTP transports only)

Variable	Default	Description
MCPG_HTTP_MAX_BODY_BYTES	1048576	(1 MiB) Request bodies above this get a 413. Counts streamed bytes, so a missing/lying Content-Length can't bypass it.
MCPG_HTTP_ALLOWED_ORIGINS	—	Comma-separated CORS allowlist. Unset = no CORS middleware (no cross-origin headers emitted).
MCPG_HTTP_HSTS_MAX_AGE	63072000	Strict-Transport-Security max-age (2 years, OWASP's current recommendation). 0 disables the HSTS header. Security headers (CSP, X-Frame-Options, X-Content-Type-Options, Referrer-Policy) are always added unless the app already set them.
MCPG_HTTP_REQUEST_TIMEOUT_SECONDS	0	Per-request wall-clock cap (504 on expiry). 0 = disabled. Leave off if you rely on long-lived SSE / streamable-http streams — a hard cap also severs those.
MCPG_HTTP_TRUSTED_HOSTS	—	Comma-separated list of allowed Host header values (wildcards like *.example.com supported). Unset = no host-header validation (current behaviour). When set, requests with a non-matching Host get a 400 via Starlette's TrustedHostMiddleware.

Multi-tenancy (SET ROLE)

Variable	Default	Description
MCPG_DEFAULT_ROLE	—	Static PG role applied to every query. Identifier-validated.
MCPG_ALLOWED_ROLES	—	Comma-separated allowlist. When set, the X-MCPG-Role header / OIDC role claim must be in this list.

Read replicas

Variable	Default	Description
MCPG_REPLICA_URLS	—	Comma-separated replica DSNs. force_readonly queries round-robin across healthy replicas; primary fallback on failure; 30 s degraded-replica retry window.

Multiple databases (read-only secondaries)

Variable	Default	Description
MCPG_SECONDARY_DATABASE_URLS	—	Comma- or newline-separated name=dsn entries naming additional read-only databases this one server can serve (e.g. analytics=postgresql://…?sslmode=require,reporting=postgresql://…?sslmode=require). Read-capable tools accept an optional database argument selecting a secondary by name; omit it for the primary. Secondaries are read-only — PostgreSQL-enforced (every query runs in a READ ONLY transaction), so writes / DDL / shell / migrate always target the primary. Names must be simple identifiers ([a-z0-9_]+), unique, and not primary (the reserved id of MCPG_DATABASE_URL). Same TLS rules as the primary DSN. Call list_databases to discover the configured ids and their reachability.

Pool / timeouts / TLS

Variable	Default	Description
MCPG_POOL_MIN_SIZE	1	Minimum pool connections.
MCPG_POOL_MAX_SIZE	5	Maximum pool connections. Must be ≥ MCPG_POOL_MIN_SIZE.
MCPG_STATEMENT_TIMEOUT_MS	30000	Per-session statement_timeout set on connection checkout. Runaway queries self-terminate.
MCPG_LOCK_TIMEOUT_MS	5000	Per-session lock_timeout. Hanging lock waits self-terminate.
MCPG_ENABLE_ANALYTICAL_QUERIES	true	Expose run_analytical_query (long-running reads on an isolated pool). Set false to withdraw the tool.
MCPG_ANALYTICAL_TIMEOUT_MS	120000	Default per-call budget for run_analytical_query (2 min).
MCPG_ANALYTICAL_MAX_TIMEOUT_MS	600000	Hard ceiling for run_analytical_query; a per-call timeout_ms is clamped to this (10 min). Must be ≥ MCPG_ANALYTICAL_TIMEOUT_MS.
MCPG_ANALYTICAL_MAX_CONCURRENCY	2	Size of the isolated analytical pool — max simultaneous run_analytical_query calls.
MCPG_ALLOW_INSECURE_TLS	false	Bypass the startup TLS check that refuses remote DSNs without sslmode=require (or stronger). Loopback hosts are always exempt.
MCPG_SHUTDOWN_DRAIN_SECONDS	30	On SIGTERM, wait up to this long for in-flight tool calls to finish before closing the pool and cursors.

Subprocess tools (MCPG_ALLOW_SHELL=true only)

Variable	Default	Description
MCPG_SHELL_TIMEOUT_SEC	60	Max wall-clock for pg_dump / pg_restore / psql invocations.
MCPG_SHELL_MAX_OUTPUT_BYTES	67108864	(64 MiB) Cap on captured stdout per subprocess call.
MCPG_SUBPROCESS_BIN_ALLOWLIST	—	Comma-separated absolute dirs the resolved pg_dump / pg_restore / psql must live under. Empty = trust PATH. Defeats a PATH-shim of these binaries.
MCPG_SUBPROCESS_CPU_SECONDS	—	Per-child RLIMIT_CPU (seconds). POSIX only; unset = inherit.
MCPG_SUBPROCESS_MEMORY_MB	—	Per-child RLIMIT_AS (MiB). POSIX only; unset = inherit.

LISTEN/NOTIFY (MCPG_ALLOW_LISTEN=true only)

Variable	Default	Description
MCPG_LISTEN_QUEUE_MAX	1000	Per-channel buffer; oldest notifications dropped on overflow.

Audit

Variable	Default	Description
MCPG_AUDIT_PERSIST	false	When true, every run_write / run_ddl call persists to a mcpg_audit.events table (auto-created idempotently).
MCPG_AUDIT_REDACT_KEYS	—	Comma-separated regex fragments added to the secret-name pattern (defaults already cover password, passwd, secret, token, api[_-]?key, bearer, authorization, database_url, dsn, conninfo).
MCPG_AUDIT_INTEGRITY	false	When true, each persisted event is signed with an HMAC chained over the previous event; the verify_audit_chain tool walks the chain and reports the first break. Requires MCPG_AUDIT_HMAC_KEY.
MCPG_AUDIT_HMAC_KEY	—	Secret key for the audit HMAC chain. Required when MCPG_AUDIT_INTEGRITY=true. Never appears in repr/logs.

Secrets backend

By default every secret is read straight from the environment. Set MCPG_SECRETS_BACKEND=file to instead load API keys / bearer token / HMAC key from a mounted file — a name in the file wins; anything absent falls back to the env var, so partial files work.

Variable	Default	Description
MCPG_SECRETS_BACKEND	env	env (read every secret from the environment) | file (overlay a secrets file on top of the environment).
MCPG_SECRETS_FILE_PATH	—	Required when MCPG_SECRETS_BACKEND=file. Path to a flat name → value map: JSON always, or YAML (.yaml/.yml) when PyYAML is installed. Covers ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY / GOOGLE_API_KEY / MCPG_NL2SQL_API_KEY, MCPG_HTTP_AUTH_TOKEN, and MCPG_AUDIT_HMAC_KEY.

Rate limiting

Variable	Default	Description
MCPG_RATE_LIMIT_ENABLED	true	Token-bucket per-tool rate limiting. Set to false to restore the pre-breaking-change unlimited behavior.
MCPG_RATE_LIMIT_MAX_REQUESTS	60	Global cap per window across all tools.
MCPG_RATE_LIMIT_WINDOW_SECONDS	60	Window length for the global quota.
MCPG_RATE_LIMIT_HEAVY_MAX	5	Cap for heavy tools (run_write, run_ddl, dump_database, etc.).
MCPG_RATE_LIMIT_HEAVY_WINDOW	60	Window length for the heavy-tool quota.

Caching & Feature flags

Variable	Default	Description
MCPG_CACHE_ENABLED	true	Enable or disable the adaptive cache layer.
MCPG_CACHE_TTL_SECONDS	300	Default cache Time-To-Live in seconds.
MCPG_CACHE_MAXSIZE	1024	Maximum LRU capacity bound for the memory cache.
MCPG_REDIS_URL	—	Optional Redis backend connection string for external, multi-node caching.
MCPG_ENABLE_HEAVY_DIAGNOSTICS	true	Toggle computationally heavy diagnostic, diagram, and advisor tools.
MCPG_ELICIT_CONFIRM_WRITES	false	When true, every write/DDL/shell/listen/migrate-tier tool call (any tool whose readOnlyHint annotation isn't true) requires an accepted interactive confirmation (ctx.elicit()) before running. Best-effort, not an enforcement boundary: it only engages for clients that both pass a request context and declare the elicitation capability during initialize — a client that omits either silently bypasses the gate and the tool runs as normal.