Skip to content
Back to search

aiguide

MarketplaceWorks with Claude CodeGitHub

MCP server and Claude plugin for Postgres skills and documentation. Helps AI coding tools generate better PostgreSQL code.

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today

Check it deeper on your machine

It has changed since its scan on 11 Nov 2026.

As a Claude Code plugin, install it and then ask Claude Code:

/plugin marketplace add keithmackay/mackayi/plugin install scanskillsafety@mackayiDo a deep scan of https://github.com/timescale/pg-aiguide with scanskillsafety

Or from a terminal, clone it and run it:

git clone https://github.com/keithmackay/scanskillsafety-skill ~/.claude/skills/scanskillsafetynode ~/.claude/skills/scanskillsafety/cli.cjs --deep 'https://github.com/timescale/pg-aiguide'

It checks the exact commit: every file, its packages against OSV (api.osv.dev), how it compares with this page's scan (findsafeskills.com receives the repository's address), and, if you agree, Claude reading every file with your own Claude subscription. It never runs the code.

Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/timescale-pg-aiguide/badge.svg)](/listings/timescale-pg-aiguide)

HTML

<a href="/listings/timescale-pg-aiguide"><img src="/api/listings/timescale-pg-aiguide/badge.svg" alt="findsafeskills safety rating" /></a>

Install

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

Agent Skills

Install curated PostgreSQL best-practice skills for your AI coding agent:

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

Or install the schema exploration skill to investigate an existing PostgreSQL database:

npx skills add timescale/pg-aiguide --skill schema-exploration

Or pick individual skills interactively:

npx skills add timescale/pg-aiguide

Works with Claude Code, Cursor, Codex, Gemini CLI, VS Code, and [40+ other agents](https://agentskills.io).

For even deeper PostgreSQL knowledge, also add the [MCP server](#mcp-server) to give your agent semantic search over the official PostgreSQL, TimescaleDB, and PostGIS manuals.

MCP Server

For semantic search over PostgreSQL, TimescaleDB, and PostGIS documentation, add the **public MCP server**:

[https://mcp.tigerdata.com/docs](https://mcp.tigerdata.com/docs)

<details> <summary>Manual MCP configuration using JSON</summary>

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

</details>

Or it can be used as a **Claude Code Plugin**:

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

Install by environment

<details> <summary>Claude Code</summary>

This repo serves as a claude code marketplace plugin. To install, run:

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

This plugin uses the skills available in the `skills` directory as well as our publicly available MCP server endpoint hosted by TigerData for searching PostgreSQL documentation.

</details>

<details> <summary> Codex </summary>

Run the following to add the MCP server to codex:

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

</details>

<details> <summary> Cursor </summary>

One-click install:

Or add the following to `.cursor/mcp.json`

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

</details>

<details> <summary> Gemini CLI </summary>

Run the following to add the MCP server to Gemini CLI:

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

</details>

<details> <summary> OpenCode </summary>

Add the following to your global OpenCode config file (`~/.config/opencode/opencode.json`), or to a project level `opencode.json`. See the [OpenCode config docs](https://opencode.ai/docs/config/) for more about file locations, and the [MCP server docs](https://opencode.ai/docs/mcp-servers/) for more about the `mcp` options.

{
  "$schema": "https://opencode.ai/config.json",
  "mcp": {
    "pg-aiguide": {
      "type": "remote",
      "url": "https://mcp.tigerdata.com/docs"
    }
  }
}

Add `use pg-aiguide` to your prompts to use the pg-aiguide tools.

</details>

<details> <summary> Visual Studio </summary>

Click the button to install:

</details>

<details> <summary> VS Code </summary>

Click the button to install:

Alternatively, run the following to add the MCP server to VS Code:

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

</details>

<details> <summary> VS Code Insiders </summary>

Click the button to install:

Alternatively, run the following to add the MCP server to VS Code Insiders:

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

</details>

<details> <summary> Windsurf </summary>

Add the following to `~/.codeium/windsurf/mcp_config.json`

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

</details>

💡 Your First Prompt

Once installed, pg-aiguide can answer Postgres questions or design schemas.

**Simple schema example prompt**

> Create a Postgres table schema for storing usernames and unique email addresses.

**Complex schema example prompt**

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

.claude-plugin/marketplace.json · Manifest · 48 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. {
  2. "name": "aiguide",
  3. "owner": {
  4. "name": "TigerData",
  5. "url": "https://tigerdata.com",
  6. "email": "support@tigerdata.com"
  7. },
  8. "metadata": {
  9. "description": "PostgreSQL documentation and ecosystem tools marketplace",
  10. "version": "1.0.0",
  11. "pluginRoot": "."
  12. },
  13. "plugins": [
  14. {
  15. "name": "pg",
  16. "source": "./",
  17. "description": "Comprehensive PostgreSQL documentation and best practices through semantic search and curated skills, including ecosystem tools like TimescaleDB and Tiger Cloud",
  18. "version": "0.6.1",
  19. "author": {
  20. "name": "TigerData",
  21. "url": "https://tigerdata.com"
  22. },
  23. "homepage": "https://tigerdata.com",
  24. "repository": "https://github.com/timescale/pg-aiguide",
  25. "license": "Apache-2.0",
  26. "keywords": [
  27. "postgresql",
  28. "postgres",
  29. "database",
  30. "sql",
  31. "skills",
  32. "aiguide",
  33. "timescaledb",
  34. "documentation",
  35. "semantic-search",
  36. "best-practices"
  37. ],
  38. "category": "database",
  39. "mcpServers": {
  40. "pg-aiguide": {
  41. "type": "http",
  42. "url": "https://mcp.tigerdata.com/docs?disable_mcp_skills=1"
  43. }
  44. },
  45. "strict": false
  46. }
  47. ]
  48. }
README.md · README · 325 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # pg-aiguide
  2. **AI-optimized PostgreSQL expertise for coding assistants**
  3. pg-aiguide helps AI coding tools write dramatically better PostgreSQL code. It provides:
  4. - **Semantic search** across the official PostgreSQL manual (version-aware)
  5. - **AI-optimized “skills”** — curated, opinionated Postgres best practices used automatically by AI agents
  6. - **Extension ecosystem docs**, starting with TimescaleDB, with more coming soon
  7. Use it as:
  8. - **Agent Skills** via `npx skills` — works with Claude Code, Cursor, Codex, Gemini CLI, and 40+ other agents
  9. - a **public MCP server** that can be used with any AI coding agent, or
  10. - a **Claude Code plugin** optimized for use with Claude's native skill support.
  11. ## ⭐ Why pg-aiguide?
  12. AI coding tools often generate Postgres code that is:
  13. - outdated
  14. - missing constraints and indexes
  15. - unaware of modern PG features
  16. - inconsistent with real-world best practices
  17. pg-aiguide fixes that by giving AI agents deep, versioned PostgreSQL knowledge and proven patterns.
  18. ### See the difference
  19. https://github.com/user-attachments/assets/5a426381-09b5-4635-9050-f55422253a3d
  20. <details>
  21. <summary>Video Transcript </summary>
  22. Prompt given to Claude Code:
  23. > Please describe the schema you would create for an e-commerce website two times, first with the tiger mcp server disabled, then with the tiger mcp server enabled. For each time, write the schema to its own file in the current working directory. Then compare the two files and let me know which approach generated the better schema, using both qualitative and quantitative reasons. For this example, only use standard Postgres.
  24. Result (summarized):
  25. - **4× more constraints**
  26. - **55% more indexes** (including partial/expression indexes)
  27. - **PG17-recommended patterns**
  28. - **Modern features** (`GENERATED ALWAYS AS IDENTITY`, `NULLS NOT DISTINCT`)
  29. - **Cleaner naming & documentation**
  30. Conclusion: _pg-aiguide produces more robust, performant, maintainable schemas._
  31. </details>
  32. ## 🚀 Quickstart
  33. ### Agent Skills
  34. Install curated PostgreSQL best-practice skills for your AI coding agent:
  35. ```bash
  36. npx skills add timescale/pg-aiguide --skill postgres
  37. ```
  38. Or install the schema exploration skill to investigate an existing PostgreSQL database:
  39. ```bash
  40. npx skills add timescale/pg-aiguide --skill schema-exploration
  41. ```
  42. Or pick individual skills interactively:
  43. ```bash
  44. npx skills add timescale/pg-aiguide
  45. ```
  46. Works with Claude Code, Cursor, Codex, Gemini CLI, VS Code, and [40+ other agents](https://agentskills.io).
  47. For even deeper PostgreSQL knowledge, also add the [MCP server](#mcp-server) to give your agent semantic search over the official PostgreSQL, TimescaleDB, and PostGIS manuals.
  48. ### MCP Server
  49. For semantic search over PostgreSQL, TimescaleDB, and PostGIS documentation, add the **public MCP server**:
  50. [https://mcp.tigerdata.com/docs](https://mcp.tigerdata.com/docs)
  51. <details>
  52. <summary>Manual MCP configuration using JSON</summary>
  53. ```json
  54. {
  55. "mcpServers": {
  56. "pg-aiguide": {
  57. "url": "https://mcp.tigerdata.com/docs"
  58. }
  59. }
  60. }
  61. ```
  62. </details>
  63. Or it can be used as a **Claude Code Plugin**:
  64. ```bash
  65. claude plugin marketplace add timescale/pg-aiguide
  66. claude plugin install pg@aiguide
  67. ```
  68. #### Install by environment
  69. [![Install in Cursor](https://img.shields.io/badge/Install_in-Cursor-000000?style=flat-square&logoColor=white)](https://cursor.com/en/install-mcp?name=pg-aiguide&config=eyJuYW1lIjoicGctYWlndWlkZSIsInR5cGUiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3AudGlnZXJkYXRhLmNvbS9kb2NzIn0=)
  70. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=pg-aiguide&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D)
  71. [![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=pg-aiguide&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D&quality=insiders)
  72. [![Install in Visual Studio](https://img.shields.io/badge/Install_in-Visual_Studio-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D)
  73. [![Install in Goose](https://goose-docs.ai/img/extension-install-dark.svg)](https://goose-docs.ai/extension?url=https%3A%2F%2Fmcp.tigerdata.com%2Fdocs&type=streamable_http&id=pg-aiguide&name=pg-aiguide&description=MCP%20Server%20for%20pg-aiguide)
  74. [![Add MCP Server pg-aiguide to LM Studio](https://files.lmstudio.ai/deeplink/mcp-install-light.svg)](https://lmstudio.ai/install-mcp?name=pg-aiguide&config=eyJuYW1lIjoicGctYWlndWlkZSIsInR5cGUiOiJodHRwIiwidXJsIjoiaHR0cHM6Ly9tY3AudGlnZXJkYXRhLmNvbS9kb2NzIn0=)
  75. <details>
  76. <summary>Claude Code</summary>
  77. This repo serves as a claude code marketplace plugin. To install, run:
  78. ```bash
  79. claude plugin marketplace add timescale/pg-aiguide
  80. claude plugin install pg@aiguide
  81. ```
  82. This plugin uses the skills available in the `skills` directory as well as our
  83. publicly available MCP server endpoint hosted by TigerData for searching PostgreSQL documentation.
  84. </details>
  85. <details>
  86. <summary> Codex </summary>
  87. Run the following to add the MCP server to codex:
  88. ```bash
  89. codex mcp add --url "https://mcp.tigerdata.com/docs" pg-aiguide
  90. ```
  91. </details>
  92. <details>
  93. <summary> Cursor </summary>
  94. One-click install:
  95. [![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=pg-aiguide&config=eyJ1cmwiOiJodHRwczovL21jcC50aWdlcmRhdGEuY29tL2RvY3MifQ%3D%3D)
  96. Or add the following to `.cursor/mcp.json`
  97. ```json
  98. {
  99. "mcpServers": {
  100. "pg-aiguide": {
  101. "url": "https://mcp.tigerdata.com/docs"
  102. }
  103. }
  104. }
  105. ```
  106. </details>
  107. <details>
  108. <summary> Gemini CLI </summary>
  109. Run the following to add the MCP server to Gemini CLI:
  110. ```bash
  111. gemini mcp add -s user pg-aiguide "https://mcp.tigerdata.com/docs" -t http
  112. ```
  113. </details>
  114. <details>
  115. <summary> OpenCode </summary>
  116. Add the following to your global OpenCode config file (`~/.config/opencode/opencode.json`), or to a
  117. project level `opencode.json`. See the [OpenCode config docs](https://opencode.ai/docs/config/) for
  118. more about file locations, and the [MCP server docs](https://opencode.ai/docs/mcp-servers/) for more
  119. about the `mcp` options.
  120. ```json
  121. {
  122. "$schema": "https://opencode.ai/config.json",
  123. "mcp": {
  124. "pg-aiguide": {
  125. "type": "remote",
  126. "url": "https://mcp.tigerdata.com/docs"
  127. }
  128. }
  129. }
  130. ```
  131. Add `use pg-aiguide` to your prompts to use the pg-aiguide tools.
  132. </details>
  133. <details>
  134. <summary> Visual Studio </summary>
  135. Click the button to install:
  136. [![Install in Visual Studio](https://img.shields.io/badge/Install_in-Visual_Studio-C16FDE?style=flat-square&logo=visualstudio&logoColor=white)](https://vs-open.link/mcp-install?%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D)
  137. </details>
  138. <details>
  139. <summary> VS Code </summary>
  140. Click the button to install:
  141. [![Install in VS Code](https://img.shields.io/badge/Install_in-VS_Code-0098FF?style=flat-square&logo=visualstudiocode&logoColor=white)](https://vscode.dev/redirect/mcp/install?name=pg-aiguide&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D)
  142. Alternatively, run the following to add the MCP server to VS Code:
  143. ```bash
  144. code --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'
  145. ```
  146. </details>
  147. <details>
  148. <summary> VS Code Insiders </summary>
  149. Click the button to install:
  150. [![Install in VS Code Insiders](https://img.shields.io/badge/Install_in-VS_Code_Insiders-24bfa5?style=flat-square&logo=visualstudiocode&logoColor=white)](https://insiders.vscode.dev/redirect/mcp/install?name=pg-aiguide&config=%7B%22type%22%3A%22http%22%2C%22url%22%3A%22https%3A%2F%2Fmcp.tigerdata.com%2Fdocs%22%7D&quality=insiders)
  151. Alternatively, run the following to add the MCP server to VS Code Insiders:
  152. ```bash
  153. code-insiders --add-mcp '{"name":"pg-aiguide","type":"http","url":"https://mcp.tigerdata.com/docs"}'
  154. ```
  155. </details>
  156. <details>
  157. <summary> Windsurf </summary>
  158. Add the following to `~/.codeium/windsurf/mcp_config.json`
  159. ```json
  160. {
  161. "mcpServers": {
  162. "pg-aiguide": {
  163. "serverUrl": "https://mcp.tigerdata.com/docs"
  164. }
  165. }
  166. }
  167. ```
  168. </details>
  169. ### 💡 Your First Prompt
  170. Once installed, pg-aiguide can answer Postgres questions or design schemas.
  171. **Simple schema example prompt**
  172. > Create a Postgres table schema for storing usernames and unique email addresses.
  173. **Complex schema example prompt**
  174. > You are a senior software engineer. You are given a task to generate a Postgres schema for an IoT device company.
  175. > The devices collect environmental data on a factory floor. The data includes temperature, humidity, pressure, as
  176. > the main data points as well as other measurements that vary from device to device. Each device has a unique id
  177. > and a human-readable name. We want to record the time the data was collected as well. Analysis for recent data
  178. > includes finding outliers and anomalies based on measurements, as well as analyzing the data of particular devices for ad-hoc analysis. Historical data analysis includes analyzing the history of data for one device or getting statistics for all devices over long periods of time.
  179. ## Features
  180. ### Documentation Search (MCP Tools)
  181. - [**`search_docs`**](API.md#search_docs)
  182. Unified search tool supporting semantic (vector similarity) and keyword (BM25) search across multiple documentation sources:
  183. - `postgres` - Official PostgreSQL manual, scoped by version
  184. - `tiger` - Tiger Data's documentation (TimescaleDB and ecosystem)
  185. - `postgis` - PostGIS spatial extension documentation
  186. ### Skills (AI-Optimized Best Practices)
  187. - **[`view_skill`](API.md#view_skill)**
  188. Exposes curated, opinionated PostgreSQL best-practice skills used automatically by AI coding assistants.
  189. These skills provide guidance on:
  190. - Exploring existing PostgreSQL schemas and objects
  191. - Schema design
  192. - Indexing strategies
  193. - Data types
  194. - Data integrity and constraints
  195. - Naming conventions
  196. - Performance tuning
  197. - Modern PostgreSQL features
  198. ## 🔌 Ecosystem Documentation
  199. Supported today:
  200. - **TimescaleDB** (docs + skills)
  201. - **PostGIS** (docs)
  202. Coming soon:
  203. - **pgvector**
  204. We welcome contributions for additional extensions and tools.
  205. ## 🛠 Development
  206. See [DEVELOPMENT.md](DEVELOPMENT.md) for:
  207. - running the MCP server locally
  208. - adding new skills
  209. - adding new docs
  210. ## 🤝 Contributing
  211. We welcome:
  212. - new Postgres best-practice skills
  213. - additional documentation corpora
  214. - search quality improvements
  215. - bug reports and feature ideas
  216. ## 📄 License
  217. Apache 2.0

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.