Hn MCP Server

@cyanheads/hn-mcp-server Browse Hacker News feeds, threads, and user profiles with full-text search via MCP. STDIO or Streamable HTTP. 4 Tools

Public Hosted Server: https://hn.caseyjhand.com/mcp

Overview

Hacker News feeds, threads, and profiles. Browse ranked feeds, read full comment threads, look up users, and search stories, comments, polls, and jobs by keyword, author, date, or score.

Tools

Agent skill

Capability reference

hn_get_stories tool

• Six feed types: top, new, best, ask, show, jobs; count (default 30) and offset for pagination. One call serves at most 100 stories; a count up to 1,000 is served at 100, with a notice naming the next offset
• Returns id, type, title, url, domain, score, author, timestamp, comment count, and body text — each field omitted (not null) when HN doesn't provide it
• Enrichment reports total, offset, and hasMore; while more stories remain, truncated is set and notice names the next offset, and a notice explains empty pages (empty feed, offset past end, or every item on the page deleted/flagged). The last page carries no truncation
• Items whose fetch failed after retries, or ran past the call's 50-second time budget, are listed in failedIds with a notice naming the retry; a page where every item failed returns the classified upstream error instead of an empty list

hn_get_thread tool

• itemId plus depth (default 3; 0 returns the item with no comments) and maxComments (default 50) capping one response across all levels, alongside a fixed 64,000-byte budget on each response surface (all content[] text, nextCursor included, and the structuredContent JSON) that cuts only between comments and always returns a page's first comment whole. One call resolves at most 10 levels and 200 comments; a depth up to 100 is served at 10 and a maxComments up to 1,000 at 200, with a notice naming the comment to pass as itemId or the nextCursor that reaches the rest
• Breadth-first traversal ranked like HN — top-ranked top-level comments resolve first, replies fill in only after the level above is exhausted
• Resumable: a response stopped by maxComments, the byte budget, an upstream rate limit, or the call's 50-second time budget returns nextCursor; passing it back as cursor with the same itemId continues at the next unseen comment. The cursor carries the unvisited comments themselves, so re-ranked replies cannot shift it, and the server keeps no session state. A cursor the tool did not issue, an altered one, or one passed with a different itemId fails with invalid_cursor
• The root carries its relationships and state: parent and storyId (the story or poll the discussion belongs to) for a comment, poll for a poll option, parts and resolved options (text and votes, at every depth) for a poll, and deleted/dead markers. The content[] heading names the type — a title, Comment by , Poll option by on poll — and marks a deleted or dead root
• Flat comment list carries depth/parentId for tree reconstruction, plus childCount and an isOp flag when the comment author submitted the thread's story — on a comment root, the story at storyId, never the comment's own author. Dead and deleted comments are left out, but their live replies are still returned at their true depth, with parentId naming the omitted comment
• truncated and truncationReason (count, size, rate_limited, time, or depth when replies lie below the depth limit) are set only while comments remain unread — never on a terminal page, including a thread that loads in full at exactly the cap. notice reports deleted/dead comments omitted during traversal and the next step: the cursor, or a larger depth or a comment id as itemId, naming by ID any omitted comment whose replies the depth limit cut
• Comments and poll options whose fetch failed after retries or ran past the call's time budget are listed in failedIds, and notice names them with the retry; failed comments ride in nextCursor, so paging on retries them rather than skipping them. The root item is still returned, and a failure is never passed off as a maxComments/depth limit

hn_get_user tool

• username is case-sensitive and trimmed; includeSubmissions (default false) resolves recent submissions, with submissionCount (default 10) and submissionOffset paging through a long history. One call resolves at most 50 submissions; a submissionCount up to 1,000 is served at 50, with a notice naming the next submissionOffset
• Profile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items
• A comment submission carries its parent and a poll-option submission its poll, so either links back to what it answered
• Enrichment echoes submissionOffset and the offset to send next, or a notice when the requested offset is past the end of the history
• Submissions whose fetch failed after retries, or that the call's 50-second time budget cut, are listed in failedIds with a notice naming the retry (and the budget, when it cut them); a window where every submission failed returns the classified upstream error — Timeout when the budget cut them all
• Each response surface is held to a fixed 64,000-byte budget: an over-budget page keeps every submission and cuts the longest bodies to one shared length, flagging each with textTruncated and pointing to hn_get_thread for the whole text

hn_search_content tool

• Free-text query — typo-tolerant, with the last term also matching as a prefix; wrap a term in double quotes to match it exactly and put - before one to exclude it — plus tags (story/comment/poll/job/ask_hn/show_hn/front_page), author (the exact, case-sensitive username), storyId, dateRange, and minPoints filters; sort by relevance or date; count (default 30) and page for pagination. One call serves at most 50 hits; a count up to 1,000 is served as the page of 50 starting at the requested page's first hit, with a notice naming the count: 50 page to pass next; a non-zero page whose first hit begins no page of 50 fails with count_page_unaligned, naming a count and page that start there and, when that count is under 25, the page of 50 that holds that hit
• tags: "front_page" is the front page right now (about 30 stories), never past front pages; for an earlier window, use tags: "story" with dateRange and minPoints
• query is optional when a filter is set — list Ask HN, Show HN, polls, or jobs on their own, or pass a story's storyId with tags: "comment" to search within one thread. No query and no filter fails with missing_query_or_filter
• To check whether a page was discussed, pass its URL alone as query: the leading http://, https://, or www. is dropped before searching, so submissions under either scheme, with or without www., all match. The output query and the notice show what was searched
• dateRange bounds take ISO 8601 (YYYY, YYYY-MM, YYYY-MM-DD, or a date-time with optional offset), read as UTC and both exclusive; an empty or out-of-order range fails with invalid_date_range
• minPoints applies to stories and polls — comments and jobs carry no points, so pairing it with tags: "comment" or "job" fails with min_points_unscored_type
• view: "compact" drops the two body-text fields (text, highlights.text), which otherwise repeat a long comment twice per hit — pass a hit id to hn_get_thread to read the body. In full, a page over 64,000 bytes per response surface drops highlights.text from every hit (highlightsTextOmitted), then cuts the longest bodies to one shared length (textTruncated, with an hn_get_thread pointer) — every hit stays
• Each hit carries its type (story, comment, poll, pollopt, job) when Algolia records one. Untagged searches also return poll options, which carry only an id, author, vote count, and date — hn_get_thread reads an option's text and poll. A poll hit has no storyId; its own id is the discussion root
• Job descriptions come back as text, though keywords don't search them
• Highlight metadata (highlights.title, highlights.text, matchedWords) shows which terms matched and where; highlights.text is the matched body in full with markers
• Enrichment echoes the applied criteria — each filter set (author trimmed, dateRange as the exclusive UTC bounds applied, to the second), plus sort, count, and view with defaults filled — so a saved result says what it answers
• Enrichment reports totalHits, page, and the actual reachable totalPages — not derived from totalHits, since broad queries report far more hits than Algolia will serve. totalHitsExact: false marks totalHits as an estimate, and reachableHits: 1000 marks a search that matches more than Alg