PostgreSQL MCP Server

Exposes PostgreSQL operations as MCP Tools through a standardized JSON-RPC 2.0 transport layer, enabling LLM clients to invoke database queries and schema operations as first-class capabilities. The server implements the MCP protocol primitives (Tools, Resources, Prompts) to bridge SQL execution with LLM reasoning, using the official MCP SDK to handle bidirectional communication and request/response serialization.

Executes SQL SELECT queries against PostgreSQL with enforced read-only constraints, preventing accidental or malicious write operations (INSERT, UPDATE, DELETE, DROP). The server validates query syntax and intent before execution, using connection pooling to manage database resources efficiently and returning results as structured JSON with row-level metadata.

Logs all query executions, errors, and connection events to stdout or structured log files, enabling debugging and monitoring of MCP server behavior. The server records query text, execution time, result row count, and error details with timestamps. Supports structured logging (JSON format) for integration with log aggregation systems like ELK or Datadog.

Inspects PostgreSQL schema to expose table structures, column definitions, indexes, and relationships as queryable metadata. The server implements schema discovery tools that retrieve information_schema data and format it as structured JSON, enabling LLMs to understand database structure before generating queries. Supports filtering by schema, table, or column patterns.

Manages PostgreSQL connections using a connection pool (default 10 connections) to reuse database connections across multiple queries, reducing connection overhead and improving throughput. The server configures pool parameters (min/max connections, idle timeout, connection timeout) and handles connection lifecycle (acquire, release, error recovery) transparently. Implements connection validation and automatic reconnection on failure.

Supports parameterized SQL queries using PostgreSQL prepared statements, separating query structure from data values to prevent SQL injection attacks. The server accepts query templates with placeholder parameters and binds user-supplied values safely using the pg library's parameterization mechanism. Parameters are type-checked and escaped by the PostgreSQL driver before execution.

Executes complex SQL queries including JOINs, GROUP BY, aggregations (SUM, COUNT, AVG, MAX, MIN), subqueries, and window functions. The server parses and validates query structure to ensure read-only compliance while allowing sophisticated analytical queries. Results are returned as nested JSON structures that preserve column aliases and aggregation results.

Validates SQL syntax and execution errors, returning detailed error messages that help LLM clients understand and correct query failures. The server catches PostgreSQL errors (syntax errors, constraint violations, type mismatches) and formats them as structured JSON responses with error codes, messages, and context. Distinguishes between client errors (invalid SQL) and server errors (connection failures) for appropriate retry logic.

Executes queries within PostgreSQL transaction isolation levels (READ COMMITTED, REPEATABLE READ, SERIALIZABLE), ensuring consistent reads and preventing dirty reads or phantom reads. The server configures transaction isolation at the connection level and handles transaction boundaries transparently. Each query runs in its own transaction by default, with support for explicit transaction control if needed.

Exposes schema metadata and query results as MCP Resources, enabling MCP clients to cache and reference data across multiple interactions without re-querying. The server implements the MCP Resource primitive to serve schema information, table metadata, and optionally cached query results as named, versioned resources. Clients can subscribe to resource updates and invalidate caches when schema changes.

Accepts PostgreSQL connection parameters (host, port, database, user, password, SSL mode) via environment variables or configuration files, enabling flexible deployment across different environments without code changes. The server validates connection parameters at startup and establishes the connection pool using the provided configuration. Supports SSL/TLS encryption for secure remote connections.