pg-aiguide MCP — Use Cases, Install & Live Demo

Name: pg-aiguide MCP Server
Author: timescale

Why use it

Key features

Unified search across PostgreSQL, TimescaleDB, PostGIS docs
Version-aware — results pinned to the PG version you ask about
Curated skills on schema design, indexing, modern PG features
Hosted MCP endpoint at https://mcp.tigerdata.com/docs
Also installable as a Claude plugin

Live Demo

What it looks like in practice

pg-aiguide.replay ▶ ready

0/0

Install

Pick your client

~/Library/Application Support/Claude/claude_desktop_config.json · Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

Open Claude Desktop → Settings → Developer → Edit Config. Restart after saving.

~/.cursor/mcp.json · .cursor/mcp.json

{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

Cursor uses the same mcpServers schema as Claude Desktop. Project config wins over global.

VS Code → Cline → MCP Servers → Edit

{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

Click the MCP Servers icon in the Cline sidebar, then "Edit Configuration".

~/.codeium/windsurf/mcp_config.json

{
  "mcpServers": {
    "pg-aiguide": {
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ],
      "_inferred": true
    }
  }
}

Same shape as Claude Desktop. Restart Windsurf to pick up changes.

~/.continue/config.json

{
  "mcpServers": [
    {
      "name": "pg-aiguide",
      "command": "uvx",
      "args": [
        "pg-aiguide"
      ]
    }
  ]
}

Continue uses an array of server objects rather than a map.

~/.config/zed/settings.json

{
  "context_servers": {
    "pg-aiguide": {
      "command": {
        "path": "uvx",
        "args": [
          "pg-aiguide"
        ]
      }
    }
  }
}

Add to context_servers. Zed hot-reloads on save.

claude mcp add pg-aiguide -- uvx pg-aiguide

One-liner. Verify with claude mcp list. Remove with claude mcp remove.

Use Cases

Real-world ways to use pg-aiguide

How to get an agent to write a production-grade Postgres schema

👤 Backend engineers starting a new service ⏱ ~20 min intermediate

When to use: You want generated SQL that actually survives a code review.

Prerequisites

Add the pg-aiguide MCP — Point client at https://mcp.tigerdata.com/docs or install the Claude plugin

Flow

State the domain

I need a schema for a multi-tenant SaaS with orgs, users, projects, invites. Before writing SQL, consult pg-aiguide for schema design and identifier best practices.✓ Copied

→ Agent cites view_skill output
Review constraints + indexes

Show me every constraint you added and why. Any redundant indexes?✓ Copied

→ Per-index justification
Check modern features

Use search_docs to verify you're using GENERATED ALWAYS AS IDENTITY (not SERIAL), and NULLS NOT DISTINCT where appropriate.✓ Copied

→ Modern idioms applied

Outcome: Schema with sensible constraints, right identity columns, and indexes you can defend.

Pitfalls

Agent overuses indexes — write-heavy tables slow down — Ask for workload-aware indexing — tell it the expected reads/writes ratio

Combine with: postgres

How to get expert context when reading an EXPLAIN plan

👤 Devs optimizing a slow query ⏱ ~15 min intermediate

When to use: You have EXPLAIN ANALYZE output and don't know what's normal.

Flow

Share the plan

[paste EXPLAIN ANALYZE] — use pg-aiguide to identify what each node does and typical reasons for cost here.✓ Copied

→ Node-by-node diagnosis citing docs
Ask for index advice

Based on the plan, propose one index change. Verify the index type (BTREE vs BRIN vs partial) via pg-aiguide.✓ Copied

→ Concrete CREATE INDEX with justification

Outcome: Plan understood, change defended with docs.

Combine with: postgres

How to pick the right TimescaleDB hypertable settings

👤 Teams doing time-series on Postgres ⏱ ~15 min advanced

When to use: First hypertable in a new service — many knobs.

Flow

State ingest shape

I'll ingest ~10k rows/sec of IoT sensor data, queries are last-24h and last-30d aggregates. Consult pg-aiguide for TimescaleDB hypertable chunk interval recommendations.✓ Copied

→ Chunk interval + compression policy rationale
Draft the table

Draft the CREATE TABLE + create_hypertable + compression policy.✓ Copied

→ Full DDL

Outcome: Hypertable config tuned for your ingest rate.

Combine with: postgres

Combinations

Pair with other MCPs for X10 leverage

pg-aiguide + postgres

Consult pg-aiguide for best practices, then actually apply them via postgres MCP

Use pg-aiguide to pick the right index for orders.user_id, then apply it via postgres MCP on the dev DB. Show EXPLAIN ANALYZE before/after.✓ Copied

pg-aiguide + github

Code-review a schema migration with docs-backed reasoning

Review PR #4421 which adds a new table. Use pg-aiguide to flag any choices that diverge from idiomatic PG 16.✓ Copied

Tools

What this MCP exposes

Tool	Inputs	When to call	Cost
search_docs	query: str, product?: 'postgres'\|'timescale'\|'postgis', version?: str	Look up a specific feature, function, or setting	free
view_skill	skill: 'schema-design'\|'indexing'\|'data-types'\|'performance'	Apply best-practice guidance before writing schema	free

Cost & Limits

What this costs to run

API quota: Hosted endpoint — reasonable-use rate limits
Tokens per call: 300-1500 tokens per search result
Monetary: Free
Tip: Use view_skill for broad guidance, search_docs only when you need a specific citation.

Security

Permissions, secrets, blast radius

Minimum scopes: None — docs only

Credential storage: None

Data egress: Your queries go to mcp.tigerdata.com

Never grant: Nothing to grant; no DB access

This MCP doesn't execute SQL — pair with postgres MCP when you need to run queries.

Troubleshooting

Common errors and fixes

search_docs returns outdated info

Pin version: search_docs(query, version='17') for PG 17 specifics.

Connection to mcp.tigerdata.com fails

Check corporate firewall; fall back to the Claude plugin (local) install.

Verify: curl -I https://mcp.tigerdata.com/docs

view_skill returns generic output

Specify the skill slug exactly — unknown slugs fall back to generic summaries.

Alternatives

pg-aiguide vs others

Alternative	When to use it instead	Tradeoff
postgres MCP	You need to execute SQL, not just read docs	No curated best-practice layer
Supabase MCP	Supabase-specific project management	Supabase-locked

More

Resources

📖 Read the official README on GitHub

🐙 Browse open issues

🔍 Browse all 400+ MCP servers and Skills