Mcpg

MCPg

A production-grade [Model Context Protocol](https://modelcontextprotocol.io) 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](https://registry.modelcontextprotocol.io/v0/servers?search=io.github.devopam/mcpg)
• [mcp.so](https://mcp.so/server/mcpg---production-grade-postgresql-mcp-server/Devopam%20Mittra)
• [mcpservers.org](https://mcpservers.org/servers/devopam/mcpg)
• [Glama](https://glama.ai/mcp/servers/devopam/MCPg)
• [MCP ServerList](https://mcp-serverlist.com/mcp/mcpg)

---

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- .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

| MCPG_ACCESS_MODE | read-only | read-only \| restricted (allows write tools)