pgEdge Postgres MCP Server and Natural Language Agent
- About the pgEdge Postgres MCP Server
- Installing the MCP Server
- 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
- Reviewing Server Logs
- Authentication and Security
- Reference
- Advanced Topics
- For Developers
- Contributing
- 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:
| Client | Transport | Best For |
|---|---|---|
| CLI (Stdio) | Stdio | Local single-user development |
| CLI (HTTP) | HTTP | Multi-user or remote access |
| Web UI | HTTP | Browser-based chat interface |
| Claude Code | Stdio | Anthropic CLI agent |
| Claude Desktop | Stdio | Anthropic desktop app |
| Cursor | Stdio | AI code editor |
| Windsurf | Stdio | Codeium code editor |
| VS Code Copilot | Stdio | GitHub Copilot agent |
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.