pg-aiguide: PostgreSQL Skills and an MCP Server for AI Coding Agents

What pg-aiguide actually fixes in generated Postgres

Ask a coding assistant for an e-commerce schema and the result is usually syntactically valid and structurally thin. The README lists the failure modes it targets: code that is outdated, missing constraints and indexes, unaware of modern PostgreSQL features, and inconsistent with real-world practice. That is a documentation problem rather than a model problem. The model has read a lot of old blog posts and Stack Overflow answers, and the version-specific manual pages are a small fraction of that corpus.

pg-aiguide is aimed at people who already use an AI coding agent and write PostgreSQL by hand often enough to notice the omissions: application developers, DBAs reviewing agent output, and teams standardising schema conventions across a codebase. It is not a linter, not a migration tool, and not a replacement for reading the manual yourself. It is context injection.

The README includes a demonstration in which Claude Code is asked to describe an e-commerce schema twice, once with the server disabled and once enabled, then compare the two files. The summarised result claims four times more constraints, 55 percent more indexes including partial and expression indexes, PG17-recommended patterns, and modern features such as GENERATED ALWAYS AS IDENTITY and NULLS NOT DISTINCT. Those numbers come from the project's own video transcript, not from an independent benchmark, and the prompt explicitly restricts the exercise to standard Postgres. Treat them as a demonstration of direction, not as a measurement you can transfer to your schema.

Skills, a plugin and a hosted MCP endpoint: the three delivery paths

The repository ships the same knowledge through three channels, and picking the right one matters more than any configuration detail.

Agent Skills are markdown files under the skills directory, validated by a script named validate-skills.ts that runs as part of the check pipeline. The package.json declares a validate-skills script and skills.yaml sits at the repository root, so skill definitions are data the build verifies rather than free-form prose. Agents that support the skills convention read these files directly; the README states the install works with Claude Code, Cursor, Codex, Gemini CLI, VS Code and more than 40 other agents through the npx skills tooling.

The Claude Code plugin is a marketplace entry defined under .claude-plugin/. Installing it wires both the skills directory and the hosted MCP endpoint into Claude Code, so you get curated rules and manual search in one step.

The MCP server is the piece with real infrastructure behind it. The public endpoint at https://mcp.tigerdata.com/docs is hosted by TigerData and answers semantic search queries over the official PostgreSQL, TimescaleDB and PostGIS manuals, version-aware according to the README. A local deployment exists in the repository: docker-compose.yml runs a timescale/timescaledb-ha:pg18 database alongside the app container, the Dockerfile exposes port 3001, and migrations/ plus an ingest/ directory suggest a scrape-and-embed pipeline feeding a Postgres schema named by DB_SCHEMA. The .env.sample makes the dependency explicit with OPENAI_API_KEY, an optional OPENAI_BASE_URL for OpenAI-compatible endpoints, and a fixed 1536 embedding dimension that the sample says cannot be changed without modifying the database schema.

Installing pg-aiguide skills and running a first prompt

The fastest path is the skills install. This command pulls the curated postgres skill from the repository into your agent's skill directory; the README shows the --skill flag to select one skill by name, and the same command without the flag lets you choose interactively. If your agent supports the skills convention, the skill is available in the next session with no further configuration.

npx skills add timescale/pg-aiguide --skill postgres

For manual MCP configuration, the README gives this JSON block for any client that reads an mcpServers object. The name key is arbitrary; the url is the hosted endpoint and no API key or token appears anywhere in the example.

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

Claude Code users can take the plugin route instead, which registers the marketplace and then installs the plugin named pg from the aiguide marketplace. Both commands are required and in this order.

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

If you use Codex, the README gives a single command that registers the same endpoint. Gemini CLI takes an equivalent form with -s user and -t http. For Cursor, the README documents adding the same mcpServers block to .cursor/mcp.json, and for OpenCode a remote entry with type and url keys in the config file. After any of these, ask your agent to design a table with a foreign key and a partial index; the difference you should look for is the presence of explicit constraints and index definitions rather than a bare column list.

The hosted endpoint is the real trade-off

Every quickstart path in the README points at mcp.tigerdata.com. That means your agent's search queries, and whatever context it includes in them, leave your machine and reach TigerData's infrastructure. The README does not describe retention, logging or a data processing agreement for that endpoint. For a schema question that is probably acceptable. For a query that embeds a table name from an unreleased product, it may not be, and the README gives you no way to tell what happens to it.

Self-hosting is possible but not a small job. You need a Postgres instance with the schema the migrations create, an OpenAI API key or an OpenAI-compatible endpoint, and a populated corpus. The .env.sample is blunt about the embedding constraint: all data in the database must use the same embedding model, mixing models produces meaningless search results, and changing the model means re-scraping all documentation. Embedding dimensions are fixed at 1536 by the database schema. So the self-hosted path is not a configuration toggle, it is a pipeline you run and maintain.

A second limitation is scope. The extension documentation starts with TimescaleDB and the README says more are coming soon, so a team working primarily with PostGIS or another extension should check what the corpus actually covers before assuming parity. Third, the skills are opinionated by design. If your organisation has schema conventions that differ from the curated rules, the agent will follow the skill and contradict your house style, and the README does not document a way to override individual rules.

How pg-aiguide differs from pointing your agent at the manual

The obvious alternative is retrieval over the PostgreSQL documentation you already have, either by pasting manual pages into context or by running your own vector store over a docs dump. The difference is in who maintains the corpus and the opinions. A self-built index gives you control over what is ingested and where queries go, but it gives you raw manual text with no editorial layer. pg-aiguide's skills are curated best practices, not manual excerpts, and that editorial pass is the part that is hard to reproduce. The trade is that you inherit someone else's judgement about what good Postgres code looks like.

A second comparison is against general-purpose documentation MCP servers that index many technologies. Those tend to cover breadth, with a few pages per tool. pg-aiguide is narrow: PostgreSQL, TimescaleDB and PostGIS, with version-aware search over the official manual. If your stack is Postgres plus three other databases, a general server may be the better single install. If Postgres is the centre of the work, the depth is the point.

Licence, maintenance and the cost of keeping up

The repository is Apache-2.0, and package.json confirms the same identifier for the published npm package @tigerdata/pg-aiguide. Apache-2.0 permits commercial use and modification and includes a patent grant, but it also requires that you preserve licence and notice files; the repository carries a NOTICE file alongside LICENSE, which is the mechanism for that. This is a description of the licence terms, not legal advice, and if you redistribute a modified version you should have someone check the notice requirements.

The last push to the repository was on 2026-09-09, nine days before this writing, and releases v0.6.0 and v0.6.1 both landed on 2026-09-04 after a gap back to v0.5.0 in April. That is a recent burst rather than a long steady cadence, and the version jump from 0.5 to 0.6 suggests the project is still settling its interfaces. The upgrade cost is low for the skills path, since skills are markdown you can diff, and higher for a self-hosted deployment, where an embedding model change forces a full re-scrape. The hosted endpoint shifts that maintenance to TigerData, at the cost of the data-flow question above.

Editorial conclusion

Adopt pg-aiguide if your agent already writes Postgres DDL and you want it to stop omitting constraints, indexes and modern syntax; the skill install is a single npx command and the hosted MCP endpoint needs no key. Skip it if you cannot send your questions to mcp.tigerdata.com, or if you need a self-hosted server, since that path requires an OpenAI key, a Postgres instance with pgvector-style schema and a full documentation re-scrape. Verify first that your agent reads SKILL.md files, and check whether the public endpoint's terms suit your organisation.

Frequently asked questions

Official sources

1. Issues
2. License: Apache-2.0
3. README
4. Releases
5. timescale/pg-aiguide on GitHub