MCPg MCP Server

MCPg

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

---

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.
• 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. 800+ 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.

---

Featured In

• mcp.so
• mcpservers.org
• Official MCP Registry (coming soon)

Install

From PyPI (recommended)

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

Verify:

mcpg --version

Docker

docker build -t mcpg https://github.com/devopam/MCPg.git
docker run --rm -p 8000:8000 \
    -e MCPG_DATABASE_URL=postgresql://user:pass@host:5432/db \
    -e MCPG_ACCESS_MODE=read-only \
    mcpg

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

Wire MCPg into Claude Desktop (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"

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. Set MCPG_HTTP_AUTH_TOKEN=... for a static bearer, or MCPG_AUTH_MODE=oidc for full JWT validation against an OIDC issuer.

---

Configuration

MCPg is configured entirely through environment variables — no config file, no flags. 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

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 of ANTHROPIC_API_KEY / OPENAI_API_KEY / GEMINI_API_KEY (or GOOGLE_API_KEY) as you have — each becomes callable. When MCPG_NL2SQL_PROVIDER is unset, MCPg picks the default in preference order anthropic → openai → gemini. The translate_nl_to_sql tool accepts an optional provider="…" argument so a caller can route between providers per call; get_server_info reports which are available.

---

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 (Anthropic, OpenAI, or Gemini; 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.

---

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 vendored SQL-safety kernel at src/mcpg/_vendor/sql/ is also MIT-licensed; see NOTICE for provenance.

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.