Pgmcp

What subnetmarco/pgmcp MCP server does

The subnetmarco/pgmcp MCP server gives AI assistants access to an existing PostgreSQL database through MCP. Users can ask questions such as which customers placed the most orders or how many orders were created on a given day. The server translates natural-language requests into SQL and returns structured results.

It is intended to work with arbitrary PostgreSQL schemas rather than a bundled application schema. No database schema changes are required. The project also includes example schemas for testing, including one with mixed-case table names and another with composite primary keys.

How it works

An MCP client connects to the server over streamable HTTP. The server connects to PostgreSQL using the DATABASE_URL connection string, inspects the available database structure, and processes requests through its MCP tools. OpenAI can be enabled for SQL generation, with gpt-4o-mini used by default when no model is specified.

The subnetmarco/pgmcp MCP server applies read-only safeguards before executing generated SQL. It also supports query timeouts, connection pooling, automatic pagination, and streaming for larger result sets. When generated SQL is invalid, the server reports the database error and a suggestion rather than terminating the service.

Results can be formatted as tables, JSON, or CSV. The separate command-line client supports asking questions, issuing text searches, sending multiple questions, and limiting the number of returned rows.

Setup and configuration

A PostgreSQL database and the DATABASE_URL environment variable are required. The server can be obtained as a platform-specific release binary, built with Go, or run using the published Docker image. The repository also documents Kubernetes manifests and a Homebrew option described as available after the first release.

The subnetmarco/pgmcp MCP server accepts these configuration variables:

• DATABASE_URL: PostgreSQL connection string; required.
• OPENAI_API_KEY: optional key for AI-assisted SQL generation.
• OPENAI_MODEL: optional model name; defaults to gpt-4o-mini.
• HTTP_ADDR: listening address; defaults to :8080.
• HTTP_PATH: MCP endpoint path; defaults to /mcp.
• AUTH_BEARER: optional bearer token for authentication.

Cursor and Claude Desktop can connect to a local instance at http://localhost:8080/mcp when the default address and path are used.

Tools and capabilities

The exposed MCP tools are:

• ask: converts a natural-language question into a SQL query and streams the result when needed.
• search: searches across text columns in the database.
• stream: provides advanced streaming and pagination for very large result sets.

The implementation handles PostgreSQL mixed-case table names and supports multiple output formats. Its write protections block operations such as INSERT, UPDATE, and DELETE, making it suited to read-oriented analytics and database exploration.

Limitations and notes

The database must be PostgreSQL; the stated compatibility covers PostgreSQL databases and their varying schemas, not arbitrary database engines. AI-powered SQL generation uses OpenAI only when an API key is supplied, so users should account for that external dependency when enabling the feature. Natural-language results still depend on the generated SQL matching the database schema; invalid queries produce an error and guidance to rephrase the request.

The project documentation describes HTTP MCP configuration rather than a direct desktop stdio configuration. Running the service also requires access to the target database and a suitable PostgreSQL connection string.