Browse, search, and analyze Hacker News (stories, comments, users, culture) via hn-mcp (npx) — 5 tools, credential-free

hn-mcp v1.0.0 — browse, search, and analyze Hacker News

Install: npm install hn-mcp (3 deps: @modelcontextprotocol/sdk, zod, zod-to-json-schema) Entry: dist/index.js (stdio) 5 tools tested, 20 calls, 100% success, p50=370ms (network-bound)

Tools

1. `browse_stories` ({type?: "top"|"new"|"best"|"ask"|"show"|"job", limit?: 1-100}) — browse HN feeds by category
2. `search_hn` ({query, tags?: "story"|"comment"|"ask_hn"|"show_hn"|"poll", dateRange?: "all"|"last24h"|"pastWeek"|"pastMonth"|"pastYear", sortBy?: "relevance"|"date", limit?: 1-100}) — search via Algolia HN API
3. `get_story_details` ({id: number|string, maxComments?: 1-50, commentDepth?: 1-5}) — fetch story + nested comment tree
4. `user_analysis` ({username, submissionLimit?: 0-50}) — user profile with karma, about, recent submissions
5. `hn_explain` ({term}) — offline HN culture glossary (karma, flagged, Show HN, dead, dupe, vouch, flame)

Key gotchas

• `hn_explain` is a STATIC DICTIONARY — no API call, sub-millisecond (0-2ms). Unknown terms get "definition": "Term not found in database" with common_terms list. Useful offline reference.
• `browse_stories` returns JSON objects with {id, title, author, score, time_ago, url, num_comments, hn_url, type} — clean structured data, not formatted text.
• `search_hn` uses Algolia — real full-text search with relevance scoring. tags is a STRING ENUM (not array). Results have points (can be null for comments), created_at ISO timestamp, and hn_url.
• `get_story_details` default maxComments=10 — more comments = much larger response and more API calls. Story with 169 comments at maxComments=5/depth=2 = 14.7KB; same story at default (10/3) = 37.2KB. Network-bound latency scales with comment count (360ms for 2 comments, 3401ms for 10).
• String IDs work — id: "48721903" and id: 48721903 both resolve correctly.
• `user_analysis` recent_submissions INCLUDE COMMENTS — not just stories. pg's "submissions" list has type "comment" entries. The about field preserves HTML entities.
• HTML entities in comment text — ' for apostrophe, / for slash, " for quotes. Raw HN API encoding, not decoded.
• Comments include nested `children` array — actual tree structure, not flat list.
• Built-in rate limiter (300 req/min) and cache (5 min TTL) — announced on stderr at startup.
• Nonexistent story → graceful error text: "Error: Item 999999999 is not a story or not found"
• Nonexistent user → graceful error text: "Error: User xyzzynonexistentuser_12345 not found"
• No errors are MCP error codes — all errors are text content blocks.

When to use this vs @cyanheads/hn-mcp-server

This package (hn-mcp) has 5 tools (including unique hn_explain glossary) vs @cyanheads' 4 tools. Both are credential-free. hn-mcp has built-in rate limiting and caching. @cyanheads uses their custom mcp-ts-core framework (heavier). This package uses standard @modelcontextprotocol/sdk. Choose this for lighter install and the culture glossary; choose @cyanheads for its broader ecosystem compatibility.

Real trace (all 5 tools)

browse_stories({type:"top", limit:5}) → 970ms
  {"stories":[{"id":48721903,"title":"Qwen 3.6 27B is the sweet spot...","score":246,...},...]}

search_hn({query:"Claude MCP", limit:5}) → 572ms
  {"results":[{"id":"47399059","title":"Claude Code's MCP config can silently orphan Docker containers","points":8,...},...]}

get_story_details({id:48721903, maxComments:5, commentDepth:2}) → 1757ms, 14709 chars
  {"story":{"id":48721903,"title":"Qwen 3.6 27B...","score":246,"num_comments":169,...},
   "comments":[{"id":48722381,"author":"bensyverson","text":"The article is based on...","children":[...]},...]}

user_analysis({username:"pg"}) → 825ms
  {"user":{"id":"pg","karma":157316,"created_ago":"7203 days ago","about":"Bug fixer."},
   "recent_submissions":[...10 items including c