pgEdge MCP Server for Postgres

- 🔒 Read-Only Protection - All queries run in read-only transactions
- 📊 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 token authentication
- 🖥️ Web Interface - Modern React-based UI with AI-powered chat for
natural language database interaction
- 🐳 Docker Support - Complete containerized deployment with Docker
Compose
- 🔐 Secure - TLS support, token auth, read-only enforcement
- 🔄 Hot Reload - Automatic reload of authentication files without server
restart

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

git clone <repository-url>
cd pgedge-postgres-mcp
make build

Claude Code: .mcp.json in each of your project directories
Claude Desktop on macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Claude Desktop on Windows: %APPDATA%\\Claude\\claude_desktop_config.json

{
  "mcpServers": {
    "pgedge": {
      "command": "/absolute/path/to/bin/pgedge-postgres-mcp"
    }
  }
}

./bin/pgedge-postgres-mcp -http -no-auth

./bin/pgedge-postgres-mcp -http -token-file tokens.json

./bin/pgedge-postgres-mcp -http -tls \
-cert server.crt \
-key server.key \
-token-file tokens.json

> Note: Authentication is enabled by default in HTTP mode. Use -no-auth to

> disable it for local development, or provide an authentication token file with

> -token-file. See the

> Authentication Guide for token setup.

API Endpoint: POST http://localhost:8080/mcp/v1
Example request (with authentication):

Example request (without authentication):

cp examples/pgedge-postgres-mcp-stdio.yaml.example bin/pgedge-postgres-mcp-stdio.yaml

cp examples/pgedge-nla-cli-stdio.yaml.example bin/pgedge-nla-cli-stdio.yaml

./start_cli_stdio.sh
cp examples/pgedge-nla-cli-http.yaml.example bin/pgedge-nla-cli-http.yaml

./start_cli_http.sh

Features:
- 💬 Natural language database queries powered by Claude, GPT, or Ollama
- 🔧 Dual mode support (stdio subprocess or HTTP API)
- 💰 Anthropic prompt caching (90% cost reduction on repeated queries)
- ⚡ Runtime configuration with slash commands
- 📝 Persistent command history with readline support
- 🎨 PostgreSQL-themed UI with animations

Example queries:
- What tables are in my database?
- Show me the 10 most recent orders
- Which customers have placed more than 5 orders?
- Find documents similar to 'PostgreSQL performance tuning'

API Key Configuration:

The CLI client supports three ways to provide LLM API keys (in priority order):

1. Environment variables (recommended for development):

   export ANTHROPIC_API_KEY="sk-ant-..."

   export OPENAI_API_KEY="sk-proj-..."

   

2. API key files (recommended for production):

   echo "sk-ant-..." > ~/.anthropic-api-key

   chmod 600 ~/.anthropic-api-key

   

3. Configuration file values (not recommended - use env vars or files
instead)

See Using the CLI Client for detailed documentation.

cp examples/pgedge-postgres-mcp-http.yaml.example bin/pgedge-postgres-mcp-http.yaml
cp examples/pgedge-postgres-mcp-users.yaml.example bin/pgedge-postgres-mcp-users.yaml
cp examples/pgedge-postgres-mcp-tokens.yaml.example bin/pgedge-postgres-mcp-tokens.yaml

nano bin/pgedge-postgres-mcp-http.yaml

Deploy the entire stack with Docker Compose for production or development:

cp .env.example .env
nano .env  # Add your database connection, API keys, etc.
The project uses golangci-lint v1.x. Install it with:

Note: The configuration file .golangci.yml is compatible

with golangci-lint v1.x (not v2).

./bin/pgedge-postgres-mcp