MCPg

What devopam/MCPg MCP server does

The devopam/MCPg MCP server gives MCP-compatible clients access to PostgreSQL databases through a broad toolset. It supports catalog introspection, SQL execution, query intelligence, natural-language-to-SQL workflows, structural comparisons, search, graph queries, data movement, and operational tasks such as health checks, lock inspection, vacuum work, replica checks, dumps, migrations, and index tuning.

The implementation is PostgreSQL-specific rather than ORM-based. It uses psycopg3 and can work with PostgreSQL versions 14 through 19 according to the project’s compatibility table. Optional integrations include pgvector, TimescaleDB, PostGIS, Apache AGE, and pg_stat_statements when those capabilities are available in the database.

How it works

MCPg supports both stdio and HTTP/SSE transports. For local clients, the mcpg console script can run through uvx; HTTP deployments can expose the server and its Prometheus metrics endpoint. The HTTP transport reports tool-call totals and durations, while tool calls also produce structured audit events with credential-sensitive argument redaction.

Read-only access is the default. User-supplied SQL passes through AST parsing and an allowlist before execution, and identifier interpolation is restricted by a naming pattern. DDL, shell operations, and LISTEN/NOTIFY are disabled unless explicitly enabled. Tool annotations reflect the configured read and write gates so clients can distinguish read-only operations from tools that may change data.

Production-oriented controls include connection pooling, per-request SET ROLE handling, read-replica routing, server-side cursors, rate limiting, PostgreSQL TLS enforcement, OIDC JWT bearer authentication, and per-session statement and lock timeouts. These options make the devopam/MCPg MCP server suitable for deployments where database access needs operational controls as well as query tools.

Setup and configuration

Install the Python package from PyPI with pip install mcpg, or install it as an isolated tool with uv tool install mcpg. The executable is named mcpg. The manual stdio configuration shown for MCP clients runs uvx mcpg and supplies a PostgreSQL connection URL through MCPG_DATABASE_URL.

A Docker image is published at ghcr.io/devopam/mcpg. The documented container example maps port 8000, sets MCPG_DATABASE_URL, and sets MCPG_ACCESS_MODE=read-only. The image can also be built from the GitHub repository. Source-based development uses uv sync after cloning the project.

Claude Desktop users can install a versioned .mcpb bundle from the latest GitHub release. The bundle asks for the database URL and access mode, storing the URL in the operating system keychain. The repository also documents setup for Cursor, Windsurf, Cline, and other MCP clients.

Tools and capabilities

The documented tool surface includes:

• Inspecting schemas, tables, columns, indexes, roles, extensions, and other PostgreSQL catalog information.
• Running validated queries and examining plans, statistics, locks, health, replicas, and vacuum state.
• Generating SQL from natural-language requests and working with cursors for larger result sets.
• Comparing database structures and moving data through supported operations.
• Using hybrid search, pgvector-backed features, TimescaleDB features, and Apache AGE graph queries when available.
• Monitoring activity through audit records and Prometheus metrics.

Limitations and notes

The hosted demonstration endpoint is read-only and uses throwaway demo data; it is not a connection to a user’s database. For real workloads, the project instructs users to run MCPg alongside their own PostgreSQL instance.

Read-only mode does not mean every possible PostgreSQL operation is available: write-oriented capabilities must be enabled through configuration gates. Extension-specific tools depend on the corresponding database features being installed, and the server degrades when optional extensions are unavailable. Database credentials and access permissions remain the responsibility of the deployment.

The project is released under the MIT license. The devopam/MCPg MCP server is open source, but using it with a PostgreSQL deployment still requires an accessible database and suitable database credentials.