SuperAPI AI Directory
Partner with us中文AI newsFavorites
All toolsAI codingpgmcp

pgmcp

Natural-language queries for any PostgreSQL database, with automatic streaming and read-only safety.

Open website

About this tool

Purpose

PGMCP (PostgreSQL Model Context Protocol Server) is used to connect AI assistants to any existing PostgreSQL database, allowing users to query the database via natural language and obtain structured SQL results. It is suitable for scenarios that require conversational data exploration and execution of read-only queries, and supports integration with Cursor, Claude Desktop, the VS Code extension, and any MCP-compatible client.

Main Capabilities

  • Natural Language to SQL: Ask questions in everyday English, and the system generates SQL queries.
  • Automatic Streaming: Automatically handles large result sets.
  • Secure Read-Only Access: Blocks any write operations.
  • Text Search: Search across all text columns.
  • Multiple Output Formats: Supports table, JSON, and CSV.
  • PostgreSQL Case Sensitivity Handling: Correctly handles mixed-case table names.
  • Universal Compatibility: Works with any PostgreSQL database.
  • Error Handling: When the AI generates incorrect SQL, the system does not crash, but instead provides useful feedback and continues running.

Usage

Requires environment variables:

  • DATABASE_URL: PostgreSQL connection string pointing to an existing database.
  • OPENAI_API_KEY: OpenAI API key used for AI-driven SQL generation (optional).
  • OPENAI_MODEL: The model used (default "gpt-4o-mini").
  • HTTP_ADDR: Server address (default ":8080").
  • HTTP_PATH: MCP endpoint path (default "/mcp").
  • AUTH_BEARER: Bearer token used for authentication.

It can be run by downloading precompiled binaries (Linux, macOS, Windows), or deployed using Docker/Kubernetes. The project includes two sample database schemas:schema.sql provides a complete Amazon-like marketplace with 5,000+ records;schema_minimal.sql provides a minimal test schema containing a mixed-case "Categories" table for testing case sensitivity. It also supports connecting to the user's own database.

For integration, the configuration can be added to Cursor settings or to Claude Desktop's ~/.config/claude-desktop/claude_desktop_config.json . MCP provides three core tools:ask(converts natural language questions into SQL queries and automatically streams them),search(free-text search across all database text columns),stream(advanced streaming and pagination for very large result sets).

Suitable Scenarios

  • Data analysts or developers quickly querying a PostgreSQL database via natural language.
  • Directly accessing the database within AI programming assistants (such as Cursor, Claude Desktop) for read-only exploration.
  • Scenarios requiring secure read-only access and avoiding accidental write operations.
  • Utilizing automatic streaming and pagination when handling large datasets.

Limitations

  • Only read-only operations are supported; write operations such as INSERT, UPDATE, and DELETE are prohibited.
  • An existing PostgreSQL database is required.
  • The AI-generated SQL feature requires an OpenAI API key (optional; when not provided, perhaps only basic queries are supported? The original text does not specify the behavior without a key).
  • The project uses the Apache 2.0 license.

Related tools

Browse category