# PostgreSQL performance Tuner MCP Server

MCP server that diagnoses PostgreSQL slow queries and tests hypothetical indexes using HypoPG without writing to disk.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 30
- Author: isdaniel
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/isdaniel/pgtuner_mcp
- Updated: 2026-06-02
- HTML: https://affpapa.org/en/nevibecode/mcp/postgresql-performance-tuner-mcp-server

## What it does

The server connects to PostgreSQL using the `DATABASE_URI` environment variable and gathers telemetry from catalog tables. It pulls resource-heavy queries from `pg_stat_statements` and inspects `EXPLAIN ANALYZE` outputs. It also tracks lock waits and stalled transactions. A dedicated check monitors autovacuum progress and identifies temporary file spills caused by low `work_mem`.

Index optimization relies on the `HypoPG` extension. It builds virtual indexes inside session memory, allowing the planner to test cost reductions before writing changes to disk. Bloat tracking requires `pgstattuple`.

Without catalog read access such as the `pg_read_all_stats` role, the server cannot collect query metrics.

## Requirements
- Needs: Python and uv (commands run via uvx)
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

**Platform CLI**
```bash
claude mcp add pgtuner-mcp -- uvx pgtuner-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from pgtuner-mcp <command>

### Codex

**Platform CLI**
```bash
codex mcp add postgresql-performance-tuner-mcp-server -- uvx pgtuner-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from pgtuner-mcp <command>

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "postgresql-performance-tuner-mcp-server": {
            "command": "uvx",
            "args": [
                "pgtuner-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from pgtuner-mcp <command>

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "postgresql-performance-tuner-mcp-server": {
            "type": "stdio",
            "command": "uvx",
            "args": [
                "pgtuner-mcp"
            ]
        }
    }
}
```
uvx runs the command named after the package; if the README names another one, use uvx --from pgtuner-mcp <command>

### Gemini CLI

**Platform CLI**
```bash
gemini mcp add postgresql-performance-tuner-mcp-server uvx pgtuner-mcp
```
uvx runs the command named after the package; if the README names another one, use uvx --from pgtuner-mcp <command>

## When to use it
- extract slow queries from `pg_stat_statements` with execution stats
- test virtual index impact via `HypoPG` without allocating storage
- diagnose autovacuum progress and identify bloated tables
- inspect lock contention and long-running transactions

## Example prompts
- Inspect slow queries in `pg_stat_statements` and point out execution bottlenecks
- Simulate a candidate index on the orders table using `HypoPG` and show the plan diff
- Check autovacuum activity and report tables that require immediate vacuuming

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89408
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89433
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16717
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40409
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27669
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49845

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md