feat: add PostgreSQL tuner (pgtuner) MCP sidecar #30

New Issue

2026-02-21T18:52:17Z

cpfarhood commented

2026-02-21 18:52:17 +00:00

(Migrated from github.com)

Summary

Add a PostgreSQL performance tuning MCP server as an optional sidecar, disabled by default. This gives the AI assistant the ability to analyze slow queries, recommend indexes, detect bloat, monitor vacuum operations, and score overall database health.

Repo: https://github.com/isdaniel/pgtuner_mcp

Server Details

Image: dog830228/pgtuner_mcp
Language: Python 3.10+
Also installable via: pip install pgtuner_mcp (for stdio inside container)
Transport modes supported:
- stdio (default)
- HTTP SSE on port 8080 (customizable) — suitable for sidecar deployment
- Streamable HTTP (modern MCP protocol, stateful + stateless)

Required Configuration

Env var	Description	Required
`DATABASE_URI`	PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/db`)	Yes
`PGTUNER_EXCLUDE_USERIDS`	Comma-separated user OIDs to exclude from monitoring	No

PostgreSQL permissions needed

The database user requires:

pg_read_all_stats role
SELECT on monitored tables
Optional: pgstattuple and HypoPG extensions for full functionality

Capabilities

Slow query analysis and optimization suggestions
Index recommendations with HypoPG virtual index testing
Table and index bloat detection
Vacuum operation tracking
I/O performance pattern analysis
Comprehensive database health scoring

Proposed Implementation

Option A: SSE Sidecar (recommended — consistent with existing architecture)

Since pgtuner supports SSE natively, it fits the existing sidecar pattern used by kubernetes, flux, and homeassistant MCP servers.

# values.yaml
mcpSidecars:
  pgtuner:
    enabled: false
    image:
      repository: dog830228/pgtuner_mcp
      tag: latest  # TODO: pin to specific version
    port: 8085
    resources:
      requests:
        memory: "64Mi"
        cpu: "50m"
      limits:
        memory: "256Mi"
        cpu: "500m"

# deployment.yaml sidecar
- name: pgtuner-mcp
  image: "{{ .Values.mcpSidecars.pgtuner.image.repository }}:{{ .Values.mcpSidecars.pgtuner.image.tag }}"
  # TODO: determine exact command for SSE mode — likely needs args like --transport sse --port 8085
  ports:
    - name: pgtuner
      containerPort: {{ .Values.mcpSidecars.pgtuner.port }}
  env:
    - name: DATABASE_URI
      valueFrom:
        secretKeyRef:
          name: {{ include "antigravity.envSecretName" . }}
          key: database-uri
          optional: true
    - name: PGTUNER_EXCLUDE_USERIDS
      valueFrom:
        secretKeyRef:
          name: {{ include "antigravity.envSecretName" . }}
          key: pgtuner-exclude-userids
          optional: true

// .mcp.json entry
{
  "pgtuner": {
    "type": "sse",
    "url": "http://localhost:8085/sse"
  }
}

Option B: stdio inside mcp-extras image

Could also be installed via pip install pgtuner_mcp in the mcp-extras image variant (see #29) and run via stdio. This avoids the sidecar but requires the mcp-extras image.

Secret keys (in env secret)

database-uri — PostgreSQL connection string
pgtuner-exclude-userids — optional exclusion list

Open questions

Determine exact command/args for SSE mode in the Docker image
Pin image to a specific version tag (check Docker Hub for available tags)
Verify SSE endpoint path (/sse or different)
Determine if the image needs a custom entrypoint or if SSE is configurable via env vars

Checklist

Add pgtuner sidecar to deployment.yaml
Add pgtuner config to values.yaml
Add .mcp.json entry
Update CLAUDE.md documentation
Test SSE connectivity from devcontainer

## Summary Add a PostgreSQL performance tuning MCP server as an optional sidecar, disabled by default. This gives the AI assistant the ability to analyze slow queries, recommend indexes, detect bloat, monitor vacuum operations, and score overall database health. **Repo:** https://github.com/isdaniel/pgtuner_mcp ## Server Details - **Image:** `dog830228/pgtuner_mcp` - **Language:** Python 3.10+ - **Also installable via:** `pip install pgtuner_mcp` (for stdio inside container) - **Transport modes supported:** - stdio (default) - **HTTP SSE** on port 8080 (customizable) — suitable for sidecar deployment - Streamable HTTP (modern MCP protocol, stateful + stateless) ## Required Configuration | Env var | Description | Required | |---------|-------------|----------| | `DATABASE_URI` | PostgreSQL connection string (e.g., `postgresql://user:pass@host:5432/db`) | Yes | | `PGTUNER_EXCLUDE_USERIDS` | Comma-separated user OIDs to exclude from monitoring | No | ### PostgreSQL permissions needed The database user requires: - `pg_read_all_stats` role - `SELECT` on monitored tables - Optional: `pgstattuple` and `HypoPG` extensions for full functionality ## Capabilities - Slow query analysis and optimization suggestions - Index recommendations with HypoPG virtual index testing - Table and index bloat detection - Vacuum operation tracking - I/O performance pattern analysis - Comprehensive database health scoring ## Proposed Implementation ### Option A: SSE Sidecar (recommended — consistent with existing architecture) Since pgtuner supports SSE natively, it fits the existing sidecar pattern used by kubernetes, flux, and homeassistant MCP servers. ```yaml # values.yaml mcpSidecars: pgtuner: enabled: false image: repository: dog830228/pgtuner_mcp tag: latest # TODO: pin to specific version port: 8085 resources: requests: memory: "64Mi" cpu: "50m" limits: memory: "256Mi" cpu: "500m" ``` ```yaml # deployment.yaml sidecar - name: pgtuner-mcp image: "{{ .Values.mcpSidecars.pgtuner.image.repository }}:{{ .Values.mcpSidecars.pgtuner.image.tag }}" # TODO: determine exact command for SSE mode — likely needs args like --transport sse --port 8085 ports: - name: pgtuner containerPort: {{ .Values.mcpSidecars.pgtuner.port }} env: - name: DATABASE_URI valueFrom: secretKeyRef: name: {{ include "antigravity.envSecretName" . }} key: database-uri optional: true - name: PGTUNER_EXCLUDE_USERIDS valueFrom: secretKeyRef: name: {{ include "antigravity.envSecretName" . }} key: pgtuner-exclude-userids optional: true ``` ```json // .mcp.json entry { "pgtuner": { "type": "sse", "url": "http://localhost:8085/sse" } } ``` ### Option B: stdio inside mcp-extras image Could also be installed via `pip install pgtuner_mcp` in the mcp-extras image variant (see #29) and run via stdio. This avoids the sidecar but requires the mcp-extras image. ## Secret keys (in env secret) - `database-uri` — PostgreSQL connection string - `pgtuner-exclude-userids` — optional exclusion list ## Open questions - [ ] Determine exact command/args for SSE mode in the Docker image - [ ] Pin image to a specific version tag (check Docker Hub for available tags) - [ ] Verify SSE endpoint path (`/sse` or different) - [ ] Determine if the image needs a custom entrypoint or if SSE is configurable via env vars ## Checklist - [ ] Add pgtuner sidecar to `deployment.yaml` - [ ] Add pgtuner config to `values.yaml` - [ ] Add `.mcp.json` entry - [ ] Update CLAUDE.md documentation - [ ] Test SSE connectivity from devcontainer

cpfarhood commented

2026-02-22 12:41:17 +00:00

(Migrated from github.com)

@claude is this complete?

👀 1

cpfarhood commented

2026-02-23 01:26:52 +00:00

(Migrated from github.com)

Implemented. pgtuner MCP sidecar is available in deployment.yaml, values.yaml (disabled by default, requires DATABASE_URI), and .mcp.json. Uses SSE transport on port 8085.

Implemented. pgtuner MCP sidecar is available in `deployment.yaml`, `values.yaml` (disabled by default, requires `DATABASE_URI`), and `.mcp.json`. Uses SSE transport on port 8085.

Sign in to join this conversation.

1 Participants

Notifications

Due Date

No due date set.

Dependencies

No dependencies set.

Reference: farhoodlabs/devcontainer#30