pgEdge Postgres

You will run the pgEdge Postgres MCP Server to enable SQL queries against PostgreSQL databases using MCP-compatible clients. This server provides read-only access, AI-assisted workflows, and a modern web interface to interact with your data while keeping safety and governance in mind.

How to use

You connect an MCP client to the server either over HTTP/HTTPS or by running a local MCP process that communicates with the server. In HTTP mode, your client talks to the server’s API endpoint using token authentication. In local/stdio mode, you run the MCP server binary directly and connect via the local process to the client.

How to install

Prerequisites: ensure you have a supported environment for Go-based server components and any client you plan to use. If you plan to run in containers, Docker is supported.

# 1. Clone the repository
git clone <repository-url>
cd pgedge-postgres-mcp

# 2. Build the MCP server (Go-based project)
make build

Configuration and usage

Configure how you connect to your PostgreSQL databases and how clients authenticate. You can start the server in HTTP mode for API access or run it as a local process for direct interaction.

# HTTP mode with no authentication (development only)
./bin/pgedge-postgres-mcp -http -no-auth

# HTTP mode with token authentication (recommended)
./bin/pgedge-postgres-mcp -http -token-file tokens.json

# HTTPS with TLS and authentication
./bin/pgedge-postgres-mcp -http -tls \
  -cert server.crt \
  -key server.key \
  -token-file tokens.json

Accessing online help

If you need help while setting up or using the server, consult the available online help resources and configuration guides provided with the deployment. This will walk you through enabling features, connecting clients, and securing access.

Security and access control

The server enforces read-only transactions for all executed queries, supports token authentication, and can operate over TLS for secure communication. Use TLS certificates and token-based authentication to protect API access.

Troubleshooting tips

If clients cannot see tools or the server fails to connect to PostgreSQL, verify your connection parameters, restart the server, and check that PostgreSQL is running. Use a direct connection test to confirm the host and port are reachable.

Notes on production readiness

This MCP server is in pre-release status and should be thoroughly tested before any production use. It provides read-only access and is intended for internal tools or trusted environments rather than public-facing applications.

Building and connecting with clients

You can connect MCP-compatible clients, such as Claude Desktop, to the server in HTTP mode or by running the MCP server locally in stdio mode. The client can translate natural language questions into SQL that the server executes in a read-only fashion.

Example quick start

Install, configure, and connect using the steps below to begin querying PostgreSQL data with natural language.

Notes on deployment options

The server supports Docker-based deployment for convenient production or development environments, including a Docker Compose setup that provisions the MCP server, a web client, and authentication infrastructure.

Web client and web interface

A web-based management interface provides real-time PostgreSQL information, authentication, and UI for managing the MCP server and its connections.

More configuration details

You can specify configuration options, use environment variables for connection details, embed provider embeddings, configure the agent for multiple databases, set up supporting services like HTTP/TLS/nginx, and optionally use an encryption secret file to protect sensitive values.

Available tools

query_execution

Execute SQL queries translated from natural language or supplied directly via the MCP client.

schema_analysis

Inspect database schema, discover tables, columns, and relationships to aid query construction.

hybrid_search

Advanced search combining semantic information with traditional SQL results (BM25+MMR).

embedding_generation

Create embeddings from data to support semantic querying and similarity search.

resource_reading

Read and present database resources and metadata to the user.

prompts

Guided workflows for semantic search setup, database exploration, and query diagnostics.