How to Monitor PostgreSQL Replication Status Using MCP Server Tools

The get_replication_status tool in the call518/mcp-postgresql-ops repository automatically aggregates pg_stat_replication, replication slots, and WAL receiver metrics into a single, version-aware report to monitor PostgreSQL replication status.

The call518/mcp-postgresql-ops MCP server provides a dedicated tool to monitor PostgreSQL replication status without manual SQL scripting. It handles version compatibility transparently, supporting PostgreSQL 12 through 17, and returns formatted results via HTTP API or LLM chat interfaces.

How the Replication Monitoring Tool Works

The get_replication_status tool operates as a registered FastMCP coroutine that executes three complementary system catalog queries. Located in src/mcp_postgresql_ops/mcp_main.py (lines 315-395), this function orchestrates data collection from both primary and standby perspectives.

Version-Aware Query Generation

The tool leverages the VersionAwareQueries class in src/mcp_postgresql_ops/version_compat.py to adapt SQL syntax based on your PostgreSQL version:

• Replication slots: get_replication_slots_query() (lines 308-352) includes wal_status and safe_wal_size columns when running PostgreSQL 13 or higher.
• WAL receiver: get_wal_receiver_query() (lines 554-600) adds written_lsn and flushed_lsn metrics for PostgreSQL 16+.

The helper function get_postgresql_version() detects the server version automatically, ensuring the tool executes compatible SQL without manual configuration.

Data Aggregation and Formatting

After building the queries, the tool calls execute_query() from src/mcp_postgresql_ops/functions.py (lines 58-80) to run SQL against the configured instance. It retrieves data from:

1. pg_stat_replication – Active WAL sender processes on the primary
2. Replication slots – Logical and physical slot status
3. WAL receiver – Standby-side receiver process state

The raw results pass through format_table_data() to generate human-readable tables. If a query returns no rows (for example, querying pg_stat_replication on a standby), the tool displays a contextual message explaining the absence of data.

Calling the get_replication_status Tool

You can invoke the tool through three primary interfaces, all exposing the same underlying functionality defined in mcp_main.py.

Via HTTP API

The MCP server exposes a Swagger UI at http://<host>:8003/docs. Send a POST request to the /postgresql-ops endpoint with the tool name:

curl -X POST http://localhost:8003/postgresql-ops \
  -H "Content-Type: application/json" \
  -d '{"tool":"get_replication_status"}'

The response returns a plain-text block containing three formatted sections: replication connections, slot information, and WAL receiver status.

Via OpenWebUI or LLM Chat

Register the MCP server URL in your LLM client (e.g., OpenWebUI under Settings → Tools). Once configured, ask:

"Show me the replication status of my PostgreSQL cluster."

The LLM invokes get_replication_status automatically and renders the formatted output in the conversation thread.

Programmatically

Integrate the tool into Python applications using httpx or requests:

import httpx

url = "http://localhost:8003/postgresql-ops"
payload = {"tool": "get_replication_status"}

resp = httpx.post(url, json=payload)
print(resp.text)

This returns the same formatted report available through the web interface.

Understanding the Output

The tool returns three distinct sections that cover both primary and standby perspectives:

• Replication Connections (Primary Side): Displays client_addr, usename, application_name, state, and lag metrics (write_lag, flush_lag, replay_lag). These columns show how far behind each standby server is in applying WAL.
• Replication Slots: Lists slot_name, active state, restart_lsn, and confirmed_flush_lsn. On PostgreSQL 13+, you also see wal_status (indicating reserve or unreserved state) and safe_wal_size_mb.
• WAL Receiver Status (Standby Side): Shows the receiver process ID, status, receive_start_lsn, and on PostgreSQL 16+, written_lsn and flushed_lsn for precise lag measurement.

The connection parameters derive from environment variables defined in src/mcp_postgresql_ops/functions.py under POSTGRES_CONFIG (e.g., POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB).

Summary

• The get_replication_status tool in call518/mcp-postgresql-ops consolidates replication monitoring into a single RPC call.
• It automatically adapts queries for PostgreSQL versions 12 through 17 using VersionAwareQueries in version_compat.py.
• The tool queries pg_stat_replication, replication slots, and WAL receiver status via execute_query() in functions.py.
• Results are accessible via HTTP POST to /postgresql-ops, OpenWebUI chat, or direct Python HTTP clients.
• Output includes lag metrics, slot activity, and receiver state with version-specific columns like wal_status (PG 13+) and written_lsn (PG 16+).

Frequently Asked Questions

What PostgreSQL versions does the replication monitoring tool support?

The tool supports PostgreSQL 12 through 17. The VersionAwareQueries class in src/mcp_postgresql_ops/version_compat.py automatically detects your server version via get_postgresql_version() and adjusts the column lists accordingly, ensuring compatibility without manual intervention.

Why do I see "No active replication connections found" when running the tool?

This message appears when querying pg_stat_replication on a standby server or when no replicas are currently connected. The primary server maintains pg_stat_replication entries only when active WAL sender processes exist; standbys return empty results for this view, which the tool handles gracefully with explanatory text.

How does the tool handle authentication with the PostgreSQL instance?

Authentication uses environment variables defined in src/mcp_postgresql_ops/functions.py within the POSTGRES_CONFIG dictionary. Set POSTGRES_HOST, POSTGRES_PORT, POSTGRES_DB, POSTGRES_USER, and POSTGRES_PASSWORD before starting the MCP server. The execute_query() function reads these values to establish the database connection.

Can I monitor logical replication slots separately from physical streaming replication?

Yes. The get_replication_status tool queries all replication slots via the version-aware slot query in version_compat.py. The output includes a slot_type column distinguishing logical from physical slots, along with plugin names for logical slots and activity status for both types.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}