pgEdge/pgedge-postgres-mcp

README

pgEdge Postgres MCP Server and Natural Language Agent

About the pgEdge Postgres MCP Server
Installing the MCP Server
Configuring the MCP Server
Configuring and Using a Client Application
Reviewing Server Logs
Authentication and Security
Reference
Advanced Topics
For Developers
- For Developers - Overview
- MCP Protocol
- API Reference
- API Browser
- Client Examples
- Building Chat Clients
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.