io.github.pgEdge/postgres-mcp

pgEdge Postgres MCP Server and Natural Language Agent

• About the pgEdge Postgres MCP Server
  • pgEdge Postgres MCP Server
  • Choosing the Right Solution
  • Best Practices - Querying the Server
• Installing the MCP Server
  • Quick Start
  • Quickstart Demo with Northwind
  • Deploying on Docker
  • Deploying from Source
  • Testing the MCP Server Deployment
• Configuring the MCP Server
  • Specifying Configuration Preferences
  • Using Environment Variables to Specify Options
  • Including Provider Embeddings in a Configuration File
  • Configuring the Agent for Multiple Databases
  • Configuring Supporting Services; HTTP, systemd, and nginx
  • Using an Encryption Secret File
  • Enabling or Disabling Features
• Configuring and Using a Client Application
  • Connecting with the Web Client
  • Using the Go Chat Client
  • Configuring the Server for use with Claude Desktop
  • Configuring the Server for use with Cursor
• Reviewing Server Logs
• Authentication and Security
  • Authentication - Overview
  • Authentication - User Management
  • Authentication - OAuth
  • Authentication - Token Management
  • Security Checklist
  • Security Management
• Reference
  • Using MCP Tools
  • Using MCP Resources
  • Using MCP Prompts
  • Error Reference
  • Server Configuration File
  • API Token Configuration File
  • CLI Client Configuration Details
• Advanced Topics
  • Creating Custom Definitions
  • Configuring and Using Knowledgebase Search
  • Using the LLM Proxy
  • Row-Level and Column-Level Security
  • Distributed Deployment
• For Developers
  • For Developers - Overview
  • MCP Protocol
  • API Reference
  • API Browser
  • Client Examples
  • Building Chat Clients
    • Overview
    • Python (Stdio + Claude)
    • Python (HTTP + Ollama)
• Contributing
  • Development Setup
  • Architecture
  • Internal Architecture
  • Testing
  • CI/CD
• Accessing Online Help
• Troubleshooting
• Release Notes
• Licence

The pgEdge Postgres Model Context Protocol (MCP) server enables SQL queries against PostgreSQL databases through MCP-compatible clients. The Natural Language Agent provides supporting functionality that allows you to use natural language to form SQL queries.

Supported Versions: PostgreSQL 14 and higher.

NOT FOR PUBLIC-FACING APPLICATIONS: This MCP server provides LLMs with read access to your entire database schema and data. It should only be used for internal tools, developer workflows, or environments where all users are trusted. For public-facing applications, consider the pgEdge RAG Server instead. See the Choosing the Right Solution guide for details.

Quick Start

The Quick Start guide covers installation and setup for all supported clients:

For a guided demo with sample data, see the Quickstart Demo with Northwind.

Key Features

• Read-Only Protection - All queries run in read-only transactions by default
• Resources - Access PostgreSQL statistics and more
• Tools - Query execution, schema analysis, advanced hybrid search (BM25+MMR), embedding generation, resource reading, and more
• Prompts - Guided workflows for semantic search setup, database exploration, query diagnostics, and more
• Production Chat Client - Full-featured Go client with Anthropic prompt caching (90% cost reduction)
• HTTP/HTTPS Mode - Direct API access with user and token authentication
• Web Interface - Modern React-based UI with AI-powered chat for natural language database interaction
• Docker Support - Pre-built images on GitHub Container Registry with Docker Compose deployment
• Secure - TLS support, user and token auth, read-only enforcement
• Hot Reload - Automatic reload of authentication files without server restart

Development

Prerequisites

• Go 1.21 or higher
• PostgreSQL 14 or higher (for testing)
• golangci-lint v1.x (for linting)

Setup Linter

The project uses golangci-lint v1.x. Install it with:

go install github.com/golangci/golangci-lint/cmd/golangci-lint@latest

Note: The configuration file .golangci.yml is compatible with golangci-lint v1.x (not v2).

Building

git clone https://github.com/pgEdge/pgedge-postgres-mcp.git
cd pgedge-postgres-mcp
make build

Testing

# Run all tests
make test

# Run server tests with a database
export TEST_PGEDGE_POSTGRES_CONNECTION_STRING=\
  "postgres://localhost/postgres?sslmode=disable"
go test ./...

# Run with coverage
go test -v -cover ./...

# Run linting
make lint

Web UI Tests

The web UI has a comprehensive test suite. See web/TEST_SUMMARY.md for details.

cd web
npm test                # Run all tests
npm run test:watch      # Watch mode
npm run test:coverage   # With coverage

Security

• Read-only transaction enforcement (configurable per database)
• User and API token authentication with expiration
• TLS/HTTPS support
• SHA256 token hashing
• File permission enforcement (0600)
• Input validation and sanitization

See the Security Guide for comprehensive security documentation.

Troubleshooting

Tools not visible in Claude Desktop?

• Use absolute paths in config
• Restart Claude Desktop completely
• Check JSON syntax

Database connection errors?

• Ensure database connection is configured before starting the server (via config file, environment variables, or command-line flags)
• Verify PostgreSQL is running: pg_isready
• Check connection parameters are correct

See the Troubleshooting Guide for detailed solutions.

Support

To report an issue with the software, visit: GitHub Issues

For more information, visit docs.pgedge.com

This project is licensed under the PostgreSQL License.