hn-get

hn-get is one Hacker News data pipeline with five clients.

Documentation · Security policy · MIT license

• A JSON-first CLI for people, scripts, and agents
• A local stdio MCP server
• A Cloudflare Worker with a public HTTP API
• A remote Streamable HTTP MCP server
• RSS feeds for lists, searches, users, items, and hiring threads

Firebase supplies live items, users, and official lists. Algolia supplies search, comments, and historical activity. A small HTML parser covers public Hacker News pages such as active discussions and best comments.

Install the CLI and stdio MCP server

npx hn-get help
npm install --global hn-get

JSON stays the default output.

hn-get frontpage --limit 30
hn-get search "sqlite" --sort points --since 30d
hn-get item 40956979 --comments --depth 2
hn-get user pg --submitted-limit 20
hn-get whoishiring jobs --limit 20

Readable Markdown, text, compact JSON, and NDJSON are available when needed.

hn-get show --sort points --format markdown
hn-get newest --format ndjson

Connect the local MCP server

The npm package runs its stdio server through the main CLI.

A client config looks like this.

{
  "mcpServers": {
    "hacker-news": {
      "command": "npx",
      "args": ["-y", "hn-get", "mcp"]
    }
  }
}

The shared MCP package exposes these tools.

Tool	What it returns
hn_search	Filtered Algolia search results
hn_list	Live, searchable, or HTML-backed HN lists
hn_item	One item with an optional bounded comment tree
hn_item_comments	Searchable comments for one item
hn_user	A compact user profile
hn_user_activity	Submissions, comments, or threads
hn_replies	Replies to an item or recent user comments
hn_who_is_hiring	Results from the current hiring threads

Use the Worker API

The Worker serves the API at /v1.

GET /v1/search?q=sqlite&sort=points&limit=20
GET /v1/lists/frontpage?limit=30
GET /v1/items/40956979?comments=true&depth=2
GET /v1/items/40956979/comments?q=sqlite
GET /v1/users/pg
GET /v1/users/pg/activity?type=story
GET /v1/replies/40956979
GET /v1/whoishiring/jobs

Responses are JSON. Limits are bounded and bad input returns a JSON error with a useful HTTP status.

The remote MCP endpoint is /mcp. It uses stateless Streamable HTTP, so it shares the same tools without a Durable Object or session database.

Subscribe to RSS feeds

RSS routes work under /rss.

GET /rss/newest
GET /rss/frontpage?count=30
GET /rss/newcomments?q=sqlite
GET /rss/item?id=40956979
GET /rss/user?id=pg
GET /rss/whoishiring/jobs?q=typescript

The old hnfeed-style paths also work without the /rss prefix, including /newest, /item, and /whoishiring/jobs.

Supported feed parameters include q, points, comments, count, description, link, id, and author.

How the repo is split

apps/worker
  Cloudflare HTTP API, RSS routes, and remote MCP transport

apps/docs
  Starlight documentation served as Worker static assets

packages/core
  Hacker News and Algolia clients, normalization, limits, and parsing

packages/rss
  Feed routing and RSS rendering over core results

packages/mcp
  One MCP tool registry shared by remote HTTP and local stdio

packages/cli
  Published hn-get package, terminal output, and stdio entry point

Core owns Hacker News behavior. Each client only parses its input, calls core, and formats the result. Fixing a query or normalization bug once fixes every client.

Work on it locally

corepack enable
pnpm install
pnpm check
pnpm security:check
pnpm pack:dry-run
pnpm worker:deploy:dry-run

Useful development commands are:

pnpm dev
pnpm dev:docs
pnpm dev:cli -- search sqlite
pnpm types
pnpm build
pnpm test
pnpm lint
pnpm typecheck

Wrangler config lives in apps/worker/wrangler.jsonc. It has no account id, route, or secret. A Cloudflare Git build should use the repo root with pnpm build as the build command and pnpm worker:deploy as the deploy command.

Publish through npm trusted publishing

.github/workflows/publish.yml checks the package version on every relevant push to main. A changed version runs the full checks, inspects the tarball, and publishes with npm OIDC. There is no long-lived NPM_TOKEN.

Configure the hn-get package on npm with these trusted publisher values.

Setting	Value
Provider	GitHub Actions
Owner	iannuttall
Repository	hn-get
Workflow	publish.yml
Allowed action	npm publish

Then bump packages/cli/package.json when a release is ready. The root version is only repo metadata.

Data and output rules

• JSON remains the CLI and HTTP default.
• Search results are capped at 100 per request.
• Lists are capped at 500 items.
• Comment trees are depth and count limited.
• Upstream calls use timeouts and conservative retries.
• No client crawls linked article pages.
• There is no auth, cookie state, or hidden local config.