pgEdge Postgres MCP Server and Natural Language Agent

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
• 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 enablesSQL queries against PostgreSQL databases through MCP-compatibleclients. The Natural Language Agent provides supportingfunctionality that allows you to use natural language to formSQL queries.

Supported Versions: PostgreSQL 14 and higher.

NOT FOR PUBLIC-FACING APPLICATIONS: This MCP server providesLLMs 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-facingapplications, consider thepgEdge RAG Serverinstead. See theChoosing the Right Solution guidefor details.

Quick Start

The Quick Start guide coversinstallation and setup for all supported clients:

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

Key Features

• Read-Only Protection - All queries run in read-onlytransactions by default
• Resources - Access PostgreSQL statistics and more
• Tools - Query execution, schema analysis, advanced hybridsearch (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 withAnthropic prompt caching (90% cost reduction)
• HTTP/HTTPS Mode - Direct API access with user and tokenauthentication
• Web Interface - Modern React-based UI with AI-powered chatfor natural language database interaction
• Docker Support - Pre-built images onGitHub Container Registrywith Docker Compose deployment
• Secure - TLS support, user and token auth, read-onlyenforcement
• Hot Reload - Automatic reload of authentication fileswithout 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.ymlis 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. Seeweb/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 forcomprehensive 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 theserver (via config file, environment variables, orcommand-line flags)
• Verify PostgreSQL is running: pg_isready
• Check connection parameters are correct

See the Troubleshooting Guidefor detailed solutions.

Support

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

For more information, visitdocs.pgedge.com

This project is licensed under thePostgreSQL License.