pgdocs-mcp — PostgreSQL 18 + PostGIS docs as an MCP tool

An MCP server that gives Claude Code (or any MCP client) fast, local, ranked search over the PostgreSQL 18 and PostGIS 3.5 manuals. Scrape the official HTML once, index it locally with TF-IDF + fuzzy + exact matching, expose it over MCP. No API keys, no network calls at query time.

Built by FloreData. Companion code for the write-up "Stop Pasting Docs Into Claude. Build a Docs MCP Instead."

The four moving parts

File	Role
scrape_docs.py	BFS-crawls each manual, writes one markdown file per page (pg__*.md, postgis__*.md). The only source-aware part.
search_index.py	Generic TF-IDF + fuzzy + exact search over any directory of markdown. Pickled cache, auto-invalidated on change.
server.py	FastMCP server exposing search_docs, get_function_signature, and pgdocs:// resources.
setup.sh	Installs deps, scrapes, smoke-tests, prints the claude mcp add line.

The boundary between the scraper and everything downstream is the point: the engine is source-agnostic. Point the SOURCES list in scrape_docs.py at a different manual and the rest moves across untouched.

Quick start

Prerequisites: Python 3.10+

git clone https://github.com/FloreData/pgdocs-mcp
cd pgdocs-mcp
./setup.sh

setup.sh creates a project-local .venv, installs into it, scrapes both manuals (~5–10 min, resumable), smoke-tests, and prints a ready-to-paste registration command that points at the venv's Python. It never touches your global Python. Restart Claude Code afterwards and pgdocs appears under /mcp.

Manual setup

Same steps, by hand — still in a venv:

python3 -m venv .venv
.venv/bin/pip install -e ".[scrape]"
.venv/bin/python scrape_docs.py     # ~5–10 min, resumable
claude mcp add pgdocs -- "$(pwd)/.venv/bin/python" "$(pwd)/server.py"

Usage in Claude Code

"Search PostgreSQL docs for window functions"
"What does ST_Intersects return?"          # signature extraction
"Show me pgdocs://docs/pg/sql-select"      # direct resource
"Search PostGIS docs for 'buffer'"
"Search pgdocs for 'index' but only PostgreSQL"   # source='pg'

Search strategies

Default hybrid is right for almost everything:

• hybrid (default): all three combined, exact matches boosted — best for identifiers.
• semantic: TF-IDF cosine similarity — best for conceptual queries.
• fuzzy: typo-tolerant matching on titles/filenames.
• exact: literal substring count.

Development

.venv/bin/pip install -e ".[dev]"
.venv/bin/pytest test_pgdocs.py -v

# Re-scrape (resumable — already-scraped pages are skipped)
.venv/bin/python scrape_docs.py

# Force-rebuild one page: delete the file and re-run
rm docs/pg__sql-select.md && .venv/bin/python scrape_docs.py

The scraped docs are not in this repo

scrape_docs.py downloads the PostgreSQL and PostGIS manuals into docs/ (gitignored) and pickles a search index. Those manuals belong to their respective projects — regenerate them locally with the scraper rather than expecting them in the repo. See LICENSE: the code is MIT; the documentation it fetches is not, and remains under its upstream terms.

License

Code: MIT. Scraped documentation is not included and remains under its upstream license.