hn-mcp

MCP server for Hacker News research. Gives AI agents structured access to HN stories, discussions, and the full 47M-item archive.

Works with Claude Code, ChatGPT, Cursor, and any MCP-compatible client.

Tools

search -- find stories and comments

{ "query": "rust vs go backend", "min_points": 50 }
{ "query": "react", "type": "comment", "author": "gaearon" }
{ "query": "bitcoin", "date_from": "2017-01", "date_to": "2017-12" }

Uses Algolia for fast, ranked full-text search. Specify date_from/date_to to search the local archive instead (DuckDB over Parquet, 2006-present).

browse -- current front-page listings

{ "list": "top", "count": 30 }
{ "list": "show" }

Lists: top, new, best, ask, show, job.

thread -- read a full discussion

{ "id": 27016630 }
{ "id": 27016630, "max_comments": 0 }

Returns the story and its full comment tree (threaded, not flat). Comments are fetched in parallel. Default limit: 200 comments, depth 8.

user -- look up a user

{ "username": "pg" }

Returns karma, account age, about text, and recent submission IDs.

Data Sources

Source	Coverage	Speed	Used by
Algolia API	Indexed stories + comments	Fast	search
Firebase API	Real-time items, users, lists	Fast	browse, thread, user
Local Parquet + DuckDB	47M+ items, 2006-present	Slower	search (with date range)

Deploy

npm install
npm run build
npm start
# listening on http://localhost:8787/mcp

With Docker:

docker compose up -d

The Docker setup binds ./data as the Parquet archive directory. To download the historical archive:

bash scripts/sync-data.sh

This fetches monthly Parquet shards from HuggingFace (~12 GB total). It skips files already downloaded and re-downloads the current month.

Production (nginx + certbot)

Copy hn-mcp.conf to /etc/nginx/sites-enabled/, update server_name, then:

certbot --nginx -d your-domain.com

Connect

# Claude Code (local)
claude mcp add hn-research --url http://localhost:8787/mcp

# Claude Code (remote)
claude mcp add hn-research --url https://your-domain.com/mcp

# Cursor / VS Code -- add to .cursor/mcp.json or .vscode/mcp.json:
# { "mcpServers": { "hn-research": { "url": "http://localhost:8787/mcp" } } }

Environment

Var	Default	Description
PORT	8787	HTTP server port
HN_DATA_DIR	/data/parquet	Path to Parquet archive files

License

MIT