pg-aiguide – MCP server that teaches AI to write the correct PostgreSQL

XX

## What's the problem

AI tools are trained on a huge amount of code, including Postgres. But learning data is a slice of the past, and PostgreSQL is evolving. Without additional context, the agent:

• uses outdated patterns (SERIAL instead of GENERATED ALWAYS AS IDENTITY)
• omits restrictions and indexes that are obvious to any experienced DBA
• does not know about NULLS NOT DISTINCT, partial indexes, modern data types
• ignores best practices in naming and documenting the scheme

These are not errors; they are gaps in knowledge that pg-aiguide closes.

## How it works

pg-aiguide provides the agent with two types of tools:

search_docs - semantic + keyword (BM25) search by official PostgreSQL documentation with reference to the version. An agent can ask “how does LATERAL join work in PG17” and get an accurate answer from the official manual rather than from a random StackOverflow.

The search works from three sources:

• postgres – Official PostgreSQL documentation (with version)
• tiger – TimescaleDB documentation and TigerData ecosystem
• postgis – Documentation of PostGIS Extension

**view_skill* is a set of supervised opinionated practices that an agent applies automatically. These are not just tips – they are specific patterns on schema design, indexing, data types, constraints, naming, and performance tuning.

The entire infrastructure has already been lifted by Timescale: the public MCP server is available on https://mcp.tigerdata.com/docs, nothing needs to be installed and maintained.

## A real example: the difference in practice

The Timescale team made an honest comparison: they asked Claude Code to create a scheme for an e-commerce site twice - without pg-aiguide and with it. Results:

This unprepared demo example is the standard difference when working with real tasks.

## Installation

### Claude Code (plugin)

The most complete mode – the plugin uses both the MCP server and the built-in Claude Code skill mechanism:

claude plugin marketplace add timescale/pg-aiguide
claude plugin install pg@aiguide

### Cursor

One click through the button in README, or manually add to .cursor/mcp.json:

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

### Codex (OpenAI)

codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide

### VS Code

code --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'

### Gemini CLI

gemini mcp add -s user pg-aiguide "https://mcp.tigerdata.com/docs" -t http

### Windsurf

Add to ~/.codeium/windsurf/mcp_config.json:

{
  "mcpServers": {
    "pg-aiguide": {
      "serverUrl": "https://mcp.tigerdata.com/docs"
    }
  }
}

### Universal JSON configuration (for any MCP client)

{
  "mcpServers": {
    "pg-aiguide": {
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

## First requests after installation

Once connected, the agent will automatically start using documentation and skills. A few examples of tasks that will now give a markedly better result:

** Simple pattern:**

Create a table to store users with a unique email and username.

Complex time series scheme:

I am developing a monitoring system for IoT devices in the factory. The devices are being assembled
Temperature, humidity and pressure data once per second. Every device has
Unique ID and name. You need an effective search for the latest data specific
Devices and aggregation of historical data over long periods.

Optimization of the existing scheme:

Check this scheme for PostgreSQL 17 best practices and suggest improvements.

The agent will receive relevant patterns from pg-aiguide and apply them immediately in response.

## What's Inside: Project Structure

The repository is transparent - you can see what exactly the agent gets as context:

skills / #YAML files with skills - Opinionated practices by Postgres
rules/# Rules for specific AI IDEs (.cursor-plugin, .claude-plugin)
MCP server code (Python + TypeScript)
ingest/# Pipeline download documentation to vector database
migrations/#SQL migration for your own deployment
Docker/#Docker configuration for local startup

The skills.yaml file is the heart of the project. It is from there that the agent takes the practices that he applies automatically. The format is readable and can be contributed.

## Ecosystem documentation

In addition to the official PostgreSQL manual, pg-aiguide includes extension documentation:

Already available:

• TimescaleDB – Hypertables, Compression Policies, Continuous aggregates, Time bucket
• PostGIS – spatial data types, indexes, geometric functions

Soon:

• pgvector – vector operations, HNSW and IVFFlat indices

Extensions are exactly where AI most often generates the wrong code because their documentation is weaker in training data.

## Local startup (for development and customization)

If you want to add your own skills or connect other documentation:

git clone https://github.com/timescale/pg-aiguideX
cd pg-aiguide

Run through Docker Compose (PostgreSQL + MCP server)
docker compose up -d

# Or establish dependencies directly (Bun)
bun install
bun run dev

To add new skills, add a YAML file to the skills/ folder – the format is documented in DEVELOPMENT.md. This is the most valuable way to get into the project.

## Why this is important for the Vibcoder

Domain documented MCP servers are one of the most practical patterns for improving the quality of AI-generated code right now. pg-aiguide shows how this works in a specific example:

• you don’t have to put “Use PG17, add indexes, follow best practices” into the prompt every time
• the agent himself finds the necessary section of documentation for a specific question
• optioned skills remove ambiguity where Postgres has several working ways to do the same thing

The same approach can be applied to any library or framework – pg-aiguide is a well-working template, not just a tool for PostgreSQL.

## Conclusion

pg-aiguide is a free, publicly available MCP server from Timescale. Installed by a single command or JSON string, does not require its own infrastructure, works with most popular AI IDEs.

If you use PostgreSQL in a project and work with Cursor, VS Code, Codex or Claude Code, the connection takes less than a minute and immediately improves the quality of the generated schemas and queries.

** Repository:** github.com/timescale/pg-aiguide MCP endpoint: https://mcp.tigerdata.com/docs License: Apache 2. 0