# pg-aiguide

Gives your coding agent semantic search over the PostgreSQL, TimescaleDB and PostGIS manuals plus curated Postgres best-practice skills.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed · ★ 1874
- Author: timescale
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/timescale/pg-aiguide
- Updated: 2026-10-22
- HTML: https://affpapa.org/en/nevibecode/mcp/pg-aiguide

## What it does

pg-aiguide is a public MCP server from Timescale. It hands the agent version-aware semantic search across the official PostgreSQL manual, TimescaleDB and PostGIS docs, along with a set of skills holding opinionated Postgres patterns. It plugs into Claude, Codex, Cursor, GitHub Copilot, Windsurf, Cline and Zed.

Two ways to run it. The remote HTTP endpoint at `https://mcp.tigerdata.com/docs` needs no keys and nothing installed locally. The stdio route runs `npx -y @tigerdata/pg-aiguide` on your machine and expects `OPENAI_API_KEY` plus `PGHOST`, `PGPORT`, `PGUSER` and `PGPASSWORD`. Without those variables the local server won't come up, so start with the remote one if you just want to see what it does.

The repo also works as a Claude plugin, wiring in the same skills and the hosted endpoint. You can skip the server entirely and install skills alone with `npx skills add timescale/pg-aiguide --skill postgres`, or `--skill schema-exploration` to inspect an existing database.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://mcp.tigerdata.com/docs`
- Environment variables: `OPENAI_API_KEY`, `PGHOST`, `PGPORT`, `PGUSER`, `PGPASSWORD`, `PGDATABASE`, `DB_SCHEMA` — keys and tokens: ask the human for the values, never commit them or put them in shared files.
- Works with: PostgreSQL

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http pg-aiguide https://mcp.tigerdata.com/docs
```

2. **Platform CLI**
```bash
claude mcp add --env OPENAI_API_KEY=<OPENAI_API_KEY> --env PGHOST=<PGHOST> --env PGPORT=<PGPORT> --env PGUSER=<PGUSER> --env PGPASSWORD=<PGPASSWORD> --transport stdio pg-aiguide -- npx -y @tigerdata/pg-aiguide
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add pg-aiguide --url https://mcp.tigerdata.com/docs
```

2. **Platform CLI**
```bash
codex mcp add pg-aiguide --env OPENAI_API_KEY=<OPENAI_API_KEY> --env PGHOST=<PGHOST> --env PGPORT=<PGPORT> --env PGUSER=<PGUSER> --env PGPASSWORD=<PGPASSWORD> -- npx -y @tigerdata/pg-aiguide
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "pg-aiguide": {
            "url": "https://mcp.tigerdata.com/docs"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "pg-aiguide": {
            "command": "npx",
            "args": [
                "-y",
                "@tigerdata/pg-aiguide"
            ],
            "env": {
                "OPENAI_API_KEY": "<OPENAI_API_KEY>",
                "PGHOST": "<PGHOST>",
                "PGPORT": "<PGPORT>",
                "PGUSER": "<PGUSER>",
                "PGPASSWORD": "<PGPASSWORD>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "pg-aiguide": {
            "type": "http",
            "url": "https://mcp.tigerdata.com/docs"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "pg-aiguide": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@tigerdata/pg-aiguide"
            ],
            "env": {
                "OPENAI_API_KEY": "<OPENAI_API_KEY>",
                "PGHOST": "<PGHOST>",
                "PGPORT": "<PGPORT>",
                "PGUSER": "<PGUSER>",
                "PGPASSWORD": "<PGPASSWORD>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http pg-aiguide https://mcp.tigerdata.com/docs
```

2. **Platform CLI**
```bash
gemini mcp add -e OPENAI_API_KEY=<OPENAI_API_KEY> -e PGHOST=<PGHOST> -e PGPORT=<PGPORT> -e PGUSER=<PGUSER> -e PGPASSWORD=<PGPASSWORD> pg-aiguide npx -y @tigerdata/pg-aiguide
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- write schemas without outdated PostgreSQL constructs
- find the right manual section for a specific PG version
- add constraints and indexes the agent usually skips
- map out an existing database's structure
- check TimescaleDB or PostGIS docs while coding

## Example prompts
- Describe the schema you'd create for an e-commerce site in standard Postgres and write it to `schema.sql`
- Look up in the PostgreSQL 17 manual how to declare `GENERATED ALWAYS AS IDENTITY`
- Explore the existing database and tell me which indexes are missing

## 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

From the same set: [timescale/pg-aiguide](https://affpapa.org/en/nevibecode/by/timescale/pg-aiguide.md) — 9 cards

---
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