Postgres MCP

What postgres-mcp does

The postgres-mcp MCP server gives MCP-compatible clients access to PostgreSQL databases through a set of database-oriented tools. It supports PostgreSQL 14 and newer, and its natural-language agent helps turn user requests into SQL queries. The server is intended for internal tools, development workflows, and other environments where database users are trusted.

Queries run in read-only transactions by default. The server can expose PostgreSQL statistics and other resources, while prompts provide guided workflows for database exploration, query diagnostics, and semantic-search setup.

A React-based web interface is included for browser-based chat, and a Go chat client is available for deployments that need a fuller command-line experience. The project also provides Docker images and Docker Compose deployment support.

How it works

An MCP client connects to the server over stdio or HTTP/HTTPS. Stdio is used for local integrations such as desktop applications and code editors; HTTP supports remote or multi-user access and can use user and token authentication. The server sends database-related tools, resources, and prompts to the connected client, which allows an agent to inspect the schema, formulate SQL, and return results through the client interface.

The postgres-mcp MCP server includes advanced search support combining BM25 with vector-based methods, including maximum marginal relevance. Embedding generation is available as a tool, and provider embeddings can be included through configuration. Multiple databases can also be configured for the agent, according to the project documentation.

Setup and configuration

The repository documents installation from source and Docker-based deployment. Building from source requires Go 1.21 or newer; PostgreSQL 14 or newer is used for testing. A quick-start path is provided for supported client configurations, and a Northwind demo shows the server with sample data.

Configuration can be supplied through configuration files or environment variables. The documentation covers embedding providers, multiple databases, feature switches, supporting HTTP services, systemd, nginx, authentication, OAuth, API tokens, and an encryption secret file. HTTP deployments can use TLS/HTTPS. Authentication files support hot reload, so changes do not necessarily require a server restart.

Client-specific setup documentation is included for Claude Desktop and Cursor. The quick-start table also lists Claude Code, Windsurf, and VS Code Copilot configurations.

Tools and capabilities

The postgres-mcp MCP server includes capabilities for:

• Executing SQL queries against PostgreSQL.
• Inspecting and analyzing database schemas.
• Reading PostgreSQL resources and statistics.
• Running hybrid search with BM25 and vector techniques.
• Generating embeddings for search workflows.
• Using prompts for database exploration, diagnostics, and search setup.
• Serving natural-language database interactions through the web UI or chat client.

Security-related behavior includes token authentication, token expiration, SHA-256 token hashing, TLS support, input validation, sanitization, and permission checks for sensitive files.

Limitations and notes

This server is not intended for public-facing applications. Its connected language models can read the complete database schema and data, so it should be limited to trusted users and controlled environments. The README recommends a separate pgEdge RAG Server for public-facing use cases.

The default read-only behavior reduces the risk of unintended changes, but operators still need to configure access appropriately and review the security guidance. PostgreSQL 14 or later is required, and the available client experience depends on whether the deployment uses stdio, HTTP, or the included web interface.