Skip to content

Quick Start

Get the pgEdge Postgres MCP Server running with your preferred client in minutes.

Prerequisites

Every setup requires the following:

  • A PostgreSQL 14+ database that is running and accessible.
  • An LLM API key from Anthropic, OpenAI, or a local Ollama installation.
  • The MCP server binary, Docker image, or package (see below).

Obtaining the MCP Server

Install the MCP server from the pgEdge Enterprise package repository. First, configure the repository for your platform, then install the package.

Debian / Ubuntu:

sudo apt-get update
sudo apt-get install -y curl gnupg2 lsb-release

sudo curl -sSL \
    https://apt.pgedge.com/repodeb/pgedge-release_latest_all.deb \
    -o /tmp/pgedge-release.deb
sudo dpkg -i /tmp/pgedge-release.deb
rm -f /tmp/pgedge-release.deb

sudo apt-get update
sudo apt-get install -y pgedge-postgres-mcp

RHEL / Rocky / Alma Linux:

sudo dnf install -y \
    https://dnf.pgedge.com/reporpm/pgedge-release-latest.noarch.rpm

sudo dnf install -y pgedge-postgres-mcp

The binary is installed at /usr/bin/pgedge-postgres-mcp. The default configuration file is at /etc/pgedge/mcp-server.yaml.

Download the latest release for your platform from the GitHub Releases page. Extract the archive and note the path to the pgedge-postgres-mcp binary.

# Example for Linux amd64
tar xzf pgedge-postgres-mcp_linux_amd64.tar.gz
chmod +x pgedge-postgres-mcp

Warning

Docker is only suitable for HTTP-based deployments such as the Web UI and CLI in HTTP mode. Stdio-based clients (Claude Code, Claude Desktop, Cursor, Windsurf, and VS Code Copilot) require a local binary. Use pgEdge Packages, GitHub Release, or Build from Source for those clients.

Pull the Docker image from the GitHub Container Registry:

docker pull ghcr.io/pgedge/postgres-mcp:latest

Clone the repository and build the binary:

git clone \
    https://github.com/pgEdge/pgedge-postgres-mcp.git
cd pgedge-postgres-mcp
make build

The binary is created at bin/pgedge-postgres-mcp.

Creating a Configuration File

The MCP server reads settings from a YAML configuration file. Create a file named postgres-mcp.yaml and place it in the same directory as the binary, or specify its location with the -config flag. For pgEdge packages, the default location is /etc/pgedge/mcp-server.yaml. For builds from source, place the file at bin/postgres-mcp.yaml alongside the compiled binary.

The following example shows a minimal configuration with all available sections. Uncomment and edit the sections you need. For a full reference with detailed comments, see the Server Configuration Example and the Configuration Guide.

# Database connections (at least one is required)
databases:
    - name: "mydb"
      host: "localhost"
      port: 5432
      database: "mydb"
      user: "myuser"
      password: "mypass"
      sslmode: "prefer"
      # allow_writes: false
      # allow_llm_switching: true
      # allowed_pl_languages: []
      # available_to_users: []
      # pool_max_conns: 4
      # pool_min_conns: 0
      # pool_max_conn_idle_time: "30m"

# HTTP server (enable for Web UI, CLI HTTP mode,
# or API access)
# http:
#     enabled: true
#     address: ":8080"
#     tls:
#         enabled: false
#         cert_file: ""
#         key_file: ""
#         chain_file: ""
#     auth:
#         enabled: true
#         token_file: ""
#         user_file: ""
#         max_failed_attempts_before_lockout: 0
#         rate_limit_window_minutes: 15
#         rate_limit_max_attempts: 10

# LLM proxy (required for the Web UI only)
# llm:
#     enabled: false
#     provider: "anthropic"
#     model: "claude-sonnet-4-5"
#     anthropic_api_key_file: "~/.anthropic-api-key"
#     # anthropic_base_url: ""
#     # openai_api_key_file: "~/.openai-api-key"
#     # openai_base_url: ""
#     # ollama_url: "http://localhost:11434"
#     # max_tokens: 4096
#     # temperature: 0.7

# Embedding generation (for the generate_embedding tool)
# embedding:
#     enabled: false
#     provider: "ollama"
#     model: "nomic-embed-text"
#     # openai_api_key_file: "~/.openai-api-key"
#     # openai_base_url: ""
#     # voyage_api_key_file: "~/.voyage-api-key"
#     # voyage_base_url: ""
#     # ollama_url: "http://localhost:11434"

# Knowledgebase search
# knowledgebase:
#     enabled: false
#     database_path: ""
#     embedding_provider: "ollama"
#     embedding_model: "nomic-embed-text"
#     # embedding_voyage_api_key_file: ""
#     # embedding_voyage_base_url: ""
#     # embedding_openai_api_key_file: ""
#     # embedding_openai_base_url: ""
#     # embedding_ollama_url: "http://localhost:11434"

# Built-in features (all enabled by default)
# builtins:
#     tools:
#         query_database: true
#         get_schema_info: true
#         similarity_search: true
#         execute_explain: true
#         generate_embedding: true
#         search_knowledgebase: true
#         count_rows: true
#         llm_connection_selection: false
#     resources:
#         system_info: true
#     prompts:
#         explore_database: true
#         setup_semantic_search: true
#         diagnose_query_issue: true
#         design_schema: true

# Other options
# secret_file: ""
# trace_file: ""
# custom_definitions_path: ""
# data_dir: ""

Choosing a Client

Choose a client from the table below and follow the steps in the corresponding section.

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

CLI (Stdio)

The CLI client connects to the MCP server as a local subprocess. This mode is ideal for single-user development.

Install the CLI client from the pgEdge repository (configured in Prerequisites):

# Debian/Ubuntu: sudo apt-get install -y pgedge-nla-cli
# RHEL/Rocky:    sudo dnf install -y pgedge-nla-cli

Set your LLM API key and start the CLI:

export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

pgedge-nla-cli \
    -mcp-mode stdio \
    -mcp-server-path /usr/bin/pgedge-postgres-mcp \
    -mcp-server-config /etc/pgedge/mcp-server.yaml

Set your LLM API key and start the CLI, pointing it at the server binary and your configuration file:

export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

./pgedge-nla-cli \
    -mcp-mode stdio \
    -mcp-server-path ./pgedge-postgres-mcp \
    -mcp-server-config ./postgres-mcp.yaml

Docker is not applicable for stdio mode. The CLI client launches the MCP server as a child process, which requires a local binary. Use the pgEdge Packages, GitHub Release, or Build from Source tab to obtain the binary.

Build both the server and CLI client, then run:

make build
export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

./bin/pgedge-nla-cli \
    -mcp-mode stdio \
    -mcp-server-path ./bin/pgedge-postgres-mcp \
    -mcp-server-config ./bin/postgres-mcp.yaml

By default, the CLI looks for the server binary and postgres-mcp.yaml in the bin/ directory.

Verify the setup by typing a question at the prompt:

You: What tables are in my database?

The client should list your database tables. For full CLI documentation, see the CLI Client Guide.

CLI (HTTP)

The CLI client connects to a running MCP server over HTTP. This mode supports multiple concurrent users and remote access. Authentication is enabled by default, so you must create a user account before starting the server.

Install the CLI client from the pgEdge repository (configured in Prerequisites):

# Debian/Ubuntu: sudo apt-get install -y pgedge-nla-cli
# RHEL/Rocky:    sudo dnf install -y pgedge-nla-cli

Create a user account, start the server, then connect the CLI:

# Create a user account (runs and exits)
pgedge-postgres-mcp \
    -config /etc/pgedge/mcp-server.yaml \
    -add-user \
    -username admin -password secret123

# Start the server in HTTP mode
pgedge-postgres-mcp \
    -config /etc/pgedge/mcp-server.yaml \
    -http -addr :8080 &

# Connect the CLI
export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

pgedge-nla-cli \
    -mcp-mode http \
    -mcp-url http://localhost:8080

The CLI prompts for your username and password at startup.

Create a user account, start the server, then connect the CLI:

# Create a user account (runs and exits)
./pgedge-postgres-mcp \
    -config ./postgres-mcp.yaml \
    -add-user \
    -username admin -password secret123

# Start the server in HTTP mode
./pgedge-postgres-mcp \
    -config ./postgres-mcp.yaml \
    -http -addr :8080 &

# Connect the CLI
export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

./pgedge-nla-cli \
    -mcp-mode http \
    -mcp-url http://localhost:8080

The CLI prompts for your username and password at startup.

Clone the repository and use Docker Compose to start the server:

git clone \
    https://github.com/pgEdge/pgedge-postgres-mcp.git
cd pgedge-postgres-mcp
cp .env.example .env

Edit .env and set your database credentials, an LLM API key, and user accounts:

  • PGEDGE_DB_HOST, PGEDGE_DB_PORT, PGEDGE_DB_NAME, PGEDGE_DB_USER, PGEDGE_DB_PASSWORD
  • PGEDGE_ANTHROPIC_API_KEY or PGEDGE_OPENAI_API_KEY
  • INIT_USERS=admin:secret123

Start the containers:

docker compose up -d

The CLI client is not included in the Docker image. Download the pgedge-nla-cli binary for your platform from the GitHub Releases page, then connect to the running server:

export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

./pgedge-nla-cli \
    -mcp-mode http \
    -mcp-url http://localhost:8080

The CLI prompts for your username and password at startup.

Build the binaries, create a user account, start the server, then connect the CLI:

make build

# Create a user account (runs and exits)
./bin/pgedge-postgres-mcp \
    -config ./bin/postgres-mcp.yaml \
    -add-user \
    -username admin -password secret123

# Start the server in HTTP mode
./bin/pgedge-postgres-mcp \
    -config ./bin/postgres-mcp.yaml \
    -http -addr :8080 &

# Connect the CLI
export PGEDGE_ANTHROPIC_API_KEY=sk-ant-...

./bin/pgedge-nla-cli \
    -mcp-mode http \
    -mcp-url http://localhost:8080

The CLI prompts for your username and password at startup.

Verify the setup by typing a question at the prompt:

You: What tables are in my database?

For full CLI documentation, see the CLI Client Guide.

Web UI

The web client provides a browser-based chat interface for querying your database with natural language. The Web UI requires the LLM proxy, so you must uncomment and configure the llm section in your configuration file before starting the server. Authentication is enabled by default, so you must also create a user account.

Create a user account, then start the server in HTTP mode:

# Create a user account (runs and exits)
pgedge-postgres-mcp \
    -config /etc/pgedge/mcp-server.yaml \
    -add-user \
    -username admin -password secret123

# Start the server in HTTP mode
pgedge-postgres-mcp \
    -config /etc/pgedge/mcp-server.yaml \
    -http -addr :8080

Open http://localhost:8080 in your browser and log in with the credentials you created.

You can also install the pgedge-nla-web package for a standalone web UI served by Nginx.

Create a user account, then start the server in HTTP mode:

# Create a user account (runs and exits)
./pgedge-postgres-mcp \
    -config ./postgres-mcp.yaml \
    -add-user \
    -username admin -password secret123

# Start the server in HTTP mode
./pgedge-postgres-mcp \
    -config ./postgres-mcp.yaml \
    -http -addr :8080

Open http://localhost:8080 in your browser and log in with the credentials you created.

Clone the repository and use Docker Compose:

git clone \
    https://github.com/pgEdge/pgedge-postgres-mcp.git
cd pgedge-postgres-mcp
cp .env.example .env

Edit .env and set the following variables:

  • PGEDGE_DB_HOST, PGEDGE_DB_PORT, PGEDGE_DB_NAME, PGEDGE_DB_USER, PGEDGE_DB_PASSWORD
  • PGEDGE_ANTHROPIC_API_KEY or PGEDGE_OPENAI_API_KEY
  • INIT_USERS=admin:password123

Start the containers:

docker compose up -d

Open http://localhost:8081 in your browser and log in with the credentials you configured. Docker Compose maps the web client to port 8081 and the MCP API to port 8080.

Build the server, create a user, and start:

make build

# Create a user account (runs and exits)
./bin/pgedge-postgres-mcp \
    -config ./bin/postgres-mcp.yaml \
    -add-user \
    -username admin -password secret123

# Start the server in HTTP mode
./bin/pgedge-postgres-mcp \
    -config ./bin/postgres-mcp.yaml \
    -http -addr :8080

Open http://localhost:8080 in your browser and log in with the credentials you created.

Verify the setup by asking "What tables are in my database?" in the chat interface.

For full Web UI documentation, see the Web Client Guide.

Claude Code

Claude Code connects to the MCP server using the stdio transport. Create a .mcp.json file in your project root.

Create .mcp.json in your project directory with the following content:

{
  "mcpServers": {
    "pgedge": {
      "command": "/usr/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/etc/pgedge/mcp-server.yaml"
      ]
    }
  }
}

Create .mcp.json in your project directory with the following content:

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/postgres-mcp.yaml"
      ]
    }
  }
}

Replace the paths with the absolute paths to the downloaded binary and your configuration file.

Docker is not directly supported for stdio-based clients. Use the pgEdge Packages, GitHub Release, or Build from Source tab to obtain a local binary.

Build the server and create .mcp.json in your project directory:

cd /path/to/pgedge-postgres-mcp
make build

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/pgedge-postgres-mcp/bin/postgres-mcp.yaml"
      ]
    }
  }
}

Replace /path/to/pgedge-postgres-mcp with the absolute path to your cloned repository.

Verify the setup by asking Claude Code to list your database tables. Claude Code detects the .mcp.json file and starts the MCP server automatically.

Claude Desktop

Claude Desktop connects to the MCP server using the stdio transport. Edit the Claude Desktop configuration file to add the server.

The configuration file location depends on your operating system:

  • macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
  • Linux: ~/.config/Claude/claude_desktop_config.json
  • Windows: %APPDATA%\Claude\claude_desktop_config.json

Add the following entry to the mcpServers property in the configuration file:

{
  "mcpServers": {
    "pgedge": {
      "command": "/usr/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/etc/pgedge/mcp-server.yaml"
      ]
    }
  }
}

Add the following entry to the mcpServers property in the configuration file:

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/postgres-mcp.yaml"
      ]
    }
  }
}

Replace the paths with the absolute paths to the downloaded binary and your configuration file.

Docker is not directly supported for stdio-based clients. Use the pgEdge Packages, GitHub Release, or Build from Source tab to obtain a local binary.

Build the server binary first:

cd /path/to/pgedge-postgres-mcp
make build

Add the following entry to the mcpServers property:

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/pgedge-postgres-mcp/bin/postgres-mcp.yaml"
      ]
    }
  }
}

Restart Claude Desktop after saving the configuration file.

Verify the setup by asking Claude "What tables are in my database?" The MCP server tools should appear in the Claude Desktop tool list.

For full configuration options, see the Claude Desktop Guide.

Cursor

Cursor connects to the MCP server using the stdio transport. Edit the Cursor MCP configuration file to add the server.

The configuration file is located at ~/.cursor/mcp.json.

Add the following entry to the mcpServers property:

{
  "mcpServers": {
    "pgedge": {
      "command": "/usr/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/etc/pgedge/mcp-server.yaml"
      ]
    }
  }
}

Add the following entry to the mcpServers property:

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/postgres-mcp.yaml"
      ]
    }
  }
}

Replace the paths with the absolute paths to the downloaded binary and your configuration file.

Docker is not directly supported for stdio-based clients. Use the pgEdge Packages, GitHub Release, or Build from Source tab to obtain a local binary.

Build the server binary first:

cd /path/to/pgedge-postgres-mcp
make build

Add the following entry to the mcpServers property:

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/pgedge-postgres-mcp/bin/postgres-mcp.yaml"
      ]
    }
  }
}

Restart Cursor after saving the configuration file.

Verify the setup by asking Cursor to list your database tables. The pgEdge MCP tools should appear in the available tools list.

Windsurf

Windsurf connects to the MCP server using the stdio transport. Edit the Windsurf MCP configuration file to add the server.

The configuration file is located at ~/.codeium/windsurf/mcp_config.json.

Add the following entry to the mcpServers property:

{
  "mcpServers": {
    "pgedge": {
      "command": "/usr/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/etc/pgedge/mcp-server.yaml"
      ]
    }
  }
}

Add the following entry to the mcpServers property:

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/postgres-mcp.yaml"
      ]
    }
  }
}

Replace the paths with the absolute paths to the downloaded binary and your configuration file.

Docker is not directly supported for stdio-based clients. Use the pgEdge Packages, GitHub Release, or Build from Source tab to obtain a local binary.

Build the server binary first:

cd /path/to/pgedge-postgres-mcp
make build

Add the following entry to the mcpServers property:

{
  "mcpServers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/pgedge-postgres-mcp/bin/postgres-mcp.yaml"
      ]
    }
  }
}

Restart Windsurf after saving the configuration file.

Verify the setup by asking Windsurf to list your database tables.

VS Code Copilot

VS Code with GitHub Copilot connects to the MCP server using the stdio transport. Create a .vscode/mcp.json file in your project root.

Note

VS Code uses the servers key instead of mcpServers.

Create .vscode/mcp.json in your project directory:

{
  "servers": {
    "pgedge": {
      "command": "/usr/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/etc/pgedge/mcp-server.yaml"
      ]
    }
  }
}

Create .vscode/mcp.json in your project directory:

{
  "servers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/postgres-mcp.yaml"
      ]
    }
  }
}

Replace the paths with the absolute paths to the downloaded binary and your configuration file.

Docker is not directly supported for stdio-based clients. Use the pgEdge Packages, GitHub Release, or Build from Source tab to obtain a local binary.

Build the server binary first:

cd /path/to/pgedge-postgres-mcp
make build

Create .vscode/mcp.json in your project directory:

{
  "servers": {
    "pgedge": {
      "command": "/path/to/pgedge-postgres-mcp/bin/pgedge-postgres-mcp",
      "args": [
        "-config",
        "/path/to/pgedge-postgres-mcp/bin/postgres-mcp.yaml"
      ]
    }
  }
}

Restart VS Code after saving the configuration file.

Verify the setup by asking Copilot to list your database tables. The pgEdge MCP tools should appear in the Copilot agent tools list.

Next Steps

After verifying your setup, explore the following resources: