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 - 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
  • KB Builder Configuration Details
• Advanced Topics
  • Creating Custom Definitions
  • Configuring and Using Knowledgebase Search
  • Building a Custom Knowledge Base
  • 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
  • KB Builder
  • 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.