Mcpg

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
• Smithery
• Glama
• MCP ServerList

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

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):

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 <  date_trunc('month', now()))
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), , , , , .

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 [email protected].
• 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. Participation is governed by the Code of Conduct (Contributor Covenant 2.1).

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.