MCPg

**A production-grade Model Context Protocol

server for PostgreSQL.** It lets AI agents safely inspect, query, operate, and

tune a Postgres database — 254 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**
• **Smithery**
• **Glama**

Why MCPg

• Safe by default. Read-only access mode. Every user-supplied SQL

statement parses through a validated AST allowlist before execution.

Identifier interpolation flows through a strict

`[A-Za-z_][A-Za-z0-9_]*` regex — a design constraint that means

user input never reaches the database through string concatenation.

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](docs/installation.md#option-2--docker) 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-.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

Full reference

Core

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

Authentication (HTTP transports only)

HTTP hardening (HTTP transports only)

Multi-tenancy (`SET ROLE`)

Read replicas

Multiple databases (read-only secondaries)

Pool / timeouts / TLS

Subprocess tools (`MCPG_ALLOW_SHELL=true` only)

LISTEN/NOTIFY (`MCPG_ALLOW_LISTEN=true` only)

Audit

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.

Rate limiting

Caching & Feature flags

Natural-language SQL

MCPg auto-discovers every configured provider from the environment at

startup — set as many vendor keys as you have and each becomes callable.

Nineteen providers ship built in. Three are first-party (Anthropic,

OpenAI, Gemini); the other sixteen speak the OpenAI-compatible API with

vendor-preset endpoints: **DeepSeek, Qwen, OpenRouter, Perplexity, xAI

(Grok), Groq, Mistral, Together, Fireworks, DeepInfra, Cerebras, Nebius,

Hugging Face, GitHub Models, SambaNova, and Moonshot (Kimi)**. Every

built-in is plug-and-play — set the vendor's conventional API-key env

var and it's auto-discovered — and **any *other* OpenAI-compatible

vendor or local model server (Ollama, vLLM, LM Studio) is still

pluggable through configuration alone** via `MCPG_NL2SQL_CUSTOM_PROVIDERS`.

The whole built-in list is one declarative registry in `nl2sql.py`, so

adding a vendor or refreshing a retired default model is a one-line data

change.

When `MCPG_NL2SQL_PROVIDER` is unset, MCPg auto-picks the default in

registry order — anthropic → openai → gemini stay first so existing

deployments are unaffected. `translate_nl_to_sql` accepts an optional

`provider="…"` argument to route per call; `get_server_info` reports

which are configured.

Usage examples

The MCP tools are invoked by the agent (Claude, Cursor, Continue, …)

in response to your natural-language instructions. A handful of

illustrative round-trips:

Inspect the schema

> You: What tables live in the `public` schema, and which ones are

> the biggest by row count?

> Agent (using `list_tables` + `summarize_table` × N):

> Six tables: `customers` (1.2M rows), `orders` (4.7M), `line_items`

> (18.3M), `products` (340), `addresses` (1.4M), `audit_log`

> (45.8M — the largest, accumulates without retention).

Diagnose a slow query

> You: Why does

> `SELECT * FROM orders o JOIN line_items l ON o.id = l.order_id WHERE o.created_at > now() - interval '7 days'`

> take 8 seconds?

> Agent (using `why_is_this_slow` + `recommend_indexes`):

> `EXPLAIN ANALYZE` shows a sequential scan over `orders` (4.7M rows)

> filtered by `created_at`. There's no index on `orders.created_at`.

> Recommended:

> `CREATE INDEX CONCURRENTLY orders_created_at_idx ON orders (created_at DESC);`

> Expected improvement: ~95% reduction (index scan touches ~33K rows

> instead of full table). Run `validate_migration` on it before applying

> to confirm there's no locking surprise.

Translate plain English to SQL

> You: Find customers who placed an order this month but never

> in the previous three months — show me their email and current

> lifetime spend.

> Agent (using `translate_nl_to_sql`):

> ```sql

> SELECT c.email, SUM(l.price * l.quantity) AS lifetime_spend

> FROM customers c

> JOIN orders o ON o.customer_id = c.id

> JOIN line_items l ON l.order_id = o.id

> WHERE EXISTS (

> SELECT 1 FROM orders o2 WHERE o2.customer_id = c.id

> AND o2.created_at >= date_trunc('month', now()))

> AND NOT EXISTS (

> SELECT 1 FROM orders o3 WHERE o3.customer_id = c.id

> AND o3.created_at >= date_trunc('month', now()) - interval '3 months'

> AND o3.created_at GROUP BY c.email;

> ```

Picture the schema

> You: Draw me an ER diagram of the `public` schema.

> Agent (using `generate_schema_diagram`): *Returns a Mermaid

> diagram you can paste straight into GitHub / Notion / Obsidian.*

Audit the database

> You: How healthy is this database right now?

> Agent (using `audit_database`): Returns a graded report:

> *Memory & I/O score 92 (GOOD), Transaction & Connection 78 (WARNING:

> rollback rate 0.4%, look at app logs), Concurrency & Locks 60

> (CRITICAL: 14 backends waiting), Cleanliness & Bloat 88 (GOOD), Slow

> queries 70 (WARNING: top query template runs 5000×, mean 90 ms —

> see `optimize_query`).*

Run a guarded write

> You: Soft-delete every order older than 5 years.

> Agent (using `run_write` with `MCPG_AUDIT_PERSIST=true`): Validates

> the statement through the safe-SQL kernel, runs it inside a transaction,

> returns affected row count, persists the call (sql + arguments —

> with secrets regex-redacted — + status) to `mcpg_audit.events` for

> after-the-fact review.

For dozens more recipes — multi-tenant routing, RLS testing, NL→SQL,

hybrid vector + FTS search, Apache AGE Cypher, TimescaleDB, ORM schema

exports, server-side cursors — see `docs/cookbook.md`.

What's in the box

Compact category list. For the full, current tool reference see

`docs/tools.md`; for a guided walkthrough see

`docs/tour.md`.

• Catalog introspection — schemas, tables, columns, indexes,

constraints, views, functions, triggers, sequences, partitions,

policies, roles, grants, enums, domains, composite types, FDWs,

publications, subscriptions, extensions, generated columns.

• Query intelligence — `run_select`, `run_select_parallel`,

`explain_query`, `analyze_query_plan`, `why_is_this_slow`,

`recommend_indexes`, `analyze_workload`, `check_database_health`,

`detect_n_plus_one`, `audit_database`.

• Search — `fuzzy_search` (trigram), `full_text_search`,

`vector_search`, `hybrid_search` (pgvector + FTS via RRF),

`geo_search` (PostGIS k-NN).

• Natural language → SQL — `translate_nl_to_sql` (22 built-in

providers — Anthropic, OpenAI, Gemini, xAI, Groq, Mistral, Hugging

Face, … — plus any custom OpenAI-compatible endpoint; output passes

through the same safe-SQL kernel as hand-written queries).

• Visualisation — `generate_schema_diagram` (ER),

`generate_fk_cascade_graph` (blast-radius of `ON DELETE CASCADE`),

`generate_graph_diagram` (Apache AGE property graphs).

• Structural diff & migrations — `compare_schemas`,

`validate_migration`, staged `prepare_migration` /

`complete_migration` / `cancel_migration` workflow.

• Apache AGE graph + Cypher — `list_graphs`, `describe_graph`,

`run_cypher`, `create_graph`, `drop_graph`, `generate_graph_diagram`.

• Composite + advisor tools — `summarize_table`,

`find_unused_objects`, `find_sensitive_columns` (PII heuristic),

`lint_naming_conventions`, `test_rls_for_role`, `list_locks`,

`find_blocking_chains`, `read_pg_stat_io` (PG16+),

`generate_test_data`.

• Live ops & maintenance — `list_active_queries`,

`verify_connection_encryption` (TLS status of the live link),

`run_maintenance` (VACUUM/ANALYZE), `prune_audit_events`

(audit retention), `cancel_query`, `terminate_backend`,

`run_write`, `run_ddl`, `enable_extension`.

• Data movement — `export_query` / `export_table` (CSV/JSON),

`dump_database` / `restore_database`, `import_csv` / `import_json`

(COPY FROM STDIN), `copy_table_between_databases`.

• Server-side cursors — `open_cursor`, `fetch_cursor`,

`close_cursor`, `list_cursors` for pageable reads over millions

of rows.

• TimescaleDB — `list_hypertables`, `list_chunks`,

`create_hypertable`, `add_compression_policy`,

`add_retention_policy`.

• ORM schema exporters — Prisma, Drizzle, SQLAlchemy, sqlc,

Diesel, jOOQ, Ent, Ecto.

• Event streams — `subscribe_channel`, `poll_notifications`,

`unsubscribe_channel`, `list_notification_subscriptions` bridging

PostgreSQL `LISTEN/NOTIFY` into the MCP poll model.

• Observability — Prometheus `/metrics` endpoint +

`get_metrics_exposition` tool for stdio; structured audit trail

with regex-based credential redaction.

Documentation

• `docs/installation.md` — install + configure
• `docs/tour.md` — guided tool tour
• `docs/cookbook.md` — practical agent recipes
• `docs/tools.md` — complete tool reference
• `docs/architecture.md` — how the pieces fit together
• `docs/scaling.md` — pool sizing, replicas, performance
• `docs/security-hardening.md` — security feature roadmap
• `docs/release-process.md` — how releases ship to PyPI
• `docs/adr/` — architecture decision records
• Browse at https://devopam.github.io/MCPg/

Security

• Vulnerability reporting: see `SECURITY.md`. 90-day

coordinated-disclosure window; reports to `devopam@gmail.com`.

• Defence-in-depth: capability gates, SafeSQL kernel, identifier

allowlist, audit redaction, PG TLS enforcement at startup,

rate-limiting, OIDC JWT validation, per-session timeouts.

• See `docs/security-hardening.md` for

the living roadmap of shipped (✅) and queued (⬜) hardening items.

Privacy Policy

MCPg is self-hosted: your database contents never leave your

infrastructure, and there is no telemetry or phone-home of any kind.

The one documented exception is the opt-in `translate_nl_to_sql` tool,

which sends your question plus schema context (names, not row data) to

the LLM provider *you* configure. Full policy — data collection,

usage, storage, third-party sharing, retention, and contact — is in

`PRIVACY.md`.

Release notes & changelog

See `CHANGELOG.md` for the full version history,

`docs/release-process.md` for how releases

are cut, and the GitHub Releases

page for downloadable artifacts.

Contributing

Pull requests welcome — see `CONTRIBUTING.md` for

the dev-loop setup, test conventions, and the per-PR review

checklist.

License

MIT — see `LICENSE`. The SQL-safety kernel

(`src/mcpg/sql/`) is first-party, re-authored from the MIT-licensed

`crystaldba/postgres-mcp`; see `NOTICE` for the lineage.

Wrapped extensions — licenses you should know about

MCPg's source is MIT, but the PostgreSQL extensions it wraps each carry

their own license. The wrappers themselves are at arm's length (SQL-level

calls, no static or dynamic linking into MCPg's Python process), so

MCPg-the-project is not a derivative work of any of them. **Operators

deploying a service built on MCPg + a given extension take on whatever

obligations that extension's license imposes** — same as installing the

extension directly. The matrix below names the license per wrapped

extension so you can make an informed choice.

This matrix is a starting point — for the binding answer on your specific

deployment, consult the extension's upstream LICENSE file and (if it

matters legally) your own counsel.

> Disclaimer. Best efforts have been made to bring MCPg to

> production grade, but it remains an actively developed project and

> may contain issues. See the License terms for indemnity details.