@cyanheads/hn-mcp-server
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
Tool | Description |
| Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count |
| Get an item and its comment tree as a threaded discussion, with depth and comment-count controls and a cursor to page through long threads |
| Fetch a user profile with karma, about, and optionally a page of resolved submissions |
| Search stories, comments, polls, and jobs via Algolia by keyword, by filters alone, or both — type, author, parent story, date range, minimum points, and minimum comment count |
Agent skill
Skill | Description |
How to find a link's thread, search without Algolia's fuzzy matches, read large comment trees in full, and search what one user said. Served over MCP as |
Related MCP server: @isteam/hackernews-mcp
Capability reference
hn_get_stories tool
Six feed types:
top,new,best,ask,show,jobs;count(default 30) andoffsetfor pagination. One call serves at most 100 stories; acountup to 1,000 is served at 100, with anoticenaming the nextoffsetReturns rank, id, type, title, url, domain, score, author, timestamp, comment count, and body text — each field but
rank,id, andtypeomitted (not null) when HN doesn't provide it.rankis the story's 1-based position in the feed across pages, counted before omitted or failed items drop out, so a gap between consecutive ranks marks oneEnrichment reports
total,offset, andhasMore; while more stories remain,truncatedis set andnoticenames the nextoffset, and anoticeexplains empty pages (empty feed, offset past end, or no live item on the page). On every page that drops deleted, dead, or missing items, the final one included,noticecounts them by kind. The last page carries no truncationItems whose fetch failed after retries, or ran past the call's 50-second time budget, are listed in
failedIdswith anoticenaming the retry; a page where every item failed returns the classified error of its dominant cause instead of an empty list:upstream_rate_limitedwhen any item was rate-limited, otherwise the most frequent declared upstream reason, orupstream_no_response(Timeout) when no answer from the HN API at all was the most common failure
hn_get_thread tool
itemIdplusdepth(default 3; 0 returns the item with no comments) andmaxComments(default 25) capping one response across all levels; every comment is returned whole. One call resolves at most 10 levels and 200 comments; adepthup to 100 is served at 10 and amaxCommentsup to 1,000 at 200, with anoticenaming the comment to pass asitemIdor thenextCursorthat reaches the restBreadth-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, an upstream rate limit, or the call's 50-second time budget returnsnextCursor; passing it back ascursorwith the sameitemIdcontinues 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 differentitemIdfails withinvalid_cursorThe root carries its relationships and state:
parent,storyId(the story or poll the discussion belongs to), and, when that story is found,storyTitleandstoryUrl(absent for a text post) for a comment,childCount(its direct replies, dead and deleted included) at everydepth,pollfor a poll option,partsand resolvedoptions(text and votes, at every depth) for a poll, anddeleted/deadmarkers. Thecontent[]heading names the type — a title,Comment by <author>,Poll option by <author> on poll <id>— and marks a deleted or dead rootFlat comment list carries
depth/parentIdfor tree reconstruction, pluschildCountand anisOpflag when the comment author submitted the thread's story — on a comment root, the story atstoryId, never the comment's own author. Dead and deleted comments are left out, but their live replies are still returned at their truedepth, withparentIdnaming the omitted commenttruncatedandtruncationReason(count,rate_limited,time, ordepthwhen replies lie below the depth limit, atdepth: 0any reply of the root) are set only while comments remain unread — never on a terminal page, including a thread that loads in full at exactly the cap.noticereports deleted/dead comments omitted during traversal and the next step: the cursor, or a largerdepthor a comment id asitemId, naming by ID any omitted comment whose replies the depth limit cutComments and poll options whose fetch failed after retries or ran past the call's time budget are listed in
failedIds, andnoticenames them with the retry; failed comments ride innextCursor, so paging on retries them rather than skipping them. The root item is still returned, and a failure is never passed off as amaxComments/depthlimit
hn_get_user tool
usernameis case-sensitive, trimmed, and loses one leading@(@pglooks uppg); a name that still holds whitespace is rejected as a display name before any upstream call;includeSubmissions(default false) resolves recent submissions, withsubmissionCount(default 10) andsubmissionOffsetpaging through a long history. One call resolves at most 50 submissions; asubmissionCountup to 1,000 is served at 50, with anoticenaming the nextsubmissionOffsetProfile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items, and
noticecounts what a window drops, by kindA comment submission carries its
parentand a poll-option submission itspoll, so either links back to what it answeredEnrichment echoes
submissionOffsetand the offset to send next, or a notice when the requested offset is past the end of the historySubmissions whose fetch failed after retries, or that the call's 50-second time budget cut, are listed in
failedIdswith anoticenaming the retry (and the budget, when it cut them); a window where every submission failed returns the classified error of its dominant cause, ashn_get_storiesdoes, withupstream_no_response(Timeout) when no answer was the most common failure, the budget cutting them all includedA final window that drops dead, deleted, or absent submissions gets a
noticecounting them by kind, with no next-offset hint; one with none live also gets thesubmissionOffsetandtotal
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 — plustags(story/comment/poll/job/ask_hn/show_hn/front_page),author(the exact, case-sensitive username; trimmed, with one leading@dropped, and a name that still holds whitespace is rejected as a display name),storyId,dateRange,minPoints, andminCommentsfilters;sortby relevance or date;count(default 10) andpagefor pagination. One call serves at most 50 hits; acountup to 1,000 is served as the page of 50 starting at the requested page's first hit, with anoticenaming thecount: 50page to pass next; a non-zeropagewhose first hit begins no page of 50 fails withcount_page_unaligned, naming acountandpagethat start there and, when that count is under 25, the page of 50 that holds that hittags: "front_page"is the front page right now (about 30 stories), never past front pages; for an earlier window, usetags: "story"withdateRangeandminPointsqueryis optional when a filter is set — list Ask HN, Show HN, polls, or jobs on their own, or pass a story'sstoryIdwithtags: "comment"to search within one thread. No query and no filter fails withmissing_query_or_filterTo check whether a page was discussed, pass its URL alone as
query: the leadinghttp://,https://, orwww.is dropped before searching, so submissions under either scheme, with or withoutwww., all match. The outputqueryand the notice show what was searcheddateRangebounds 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 withinvalid_date_rangeminPointsapplies to stories and polls — comments and jobs carry no points, so pairing it withtags: "comment"or"job"fails withmin_points_unscored_typeminCommentsapplies to stories and polls the same way: any value, 0 included, excludes comments, jobs, and poll options, so an untagged search returns only stories and polls, and pairing it withtags: "comment"or"job"fails withmin_comments_unscored_type. It filters; it does not sortA comment hit carries
parentId(its story's id for a top-level comment, otherwise the parent comment's id, whichhn_get_threadreads) and, when its story links out,storyUrl; incontent[]the meta line showsparent:<id>and the story link sits on its own lineview: "compact"drops the two body-text fields (text,highlights.text), which otherwise repeat a long comment twice per hit — pass a hit id tohn_get_threadto read the body. Infull, every hit carries its whole bodyEach 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_threadreads an option's text and poll. A poll hit has nostoryId; its ownidis the discussion rootJob descriptions come back as
text, though keywords don't search themHighlight metadata (
highlights.title,highlights.text,matchedWords) shows which terms matched and where;highlights.textis the matched body in full with<em>markers, absent when Algolia returned no body highlight, which does not mean the body lacks the terms; on a hit Algolia left unhighlighted,highlightsandmatchedWordsare absent andtextstill holds the bodyEnrichment echoes the applied
criteria— each filter set (authoras searched, trimmed with one leading@dropped,dateRangeas the exclusive UTC bounds applied, to the second), plussort,count, andviewwith defaults filled — so a saved result says what it answersEnrichment reports
totalHits,page, and the actual reachabletotalPages— not derived fromtotalHits, since broad queries report far more hits than Algolia will serve.totalHitsExact: falsemarkstotalHitsas an estimate, andreachableHits: 1000marks a search that matches more than Algolia's 1,000-hit ceiling; the last page of such a search gets a notice naming the ceiling and narrowerdateRangewindows to reach the rest. While more pages remain,truncatedis set andnoticenames the nextpage; a page past the end gets a notice naming the last valid page (orpage: 0past the ceiling). Each page a notice names comes with thecountit is counted in unless that is the default, so the call works as written
Features
Built on @cyanheads/mcp-ts-core: stdio and Streamable HTTP transports, pluggable auth (none / jwt / oauth), swappable storage (in-memory, filesystem, Supabase, Cloudflare KV/R2/D1), structured logging with optional OpenTelemetry tracing.
HN-specific:
Two upstream APIs: HN's Firebase API for feeds, items, and users; Algolia's HN Search API for full-text search
Concurrent batch fetching with configurable parallelism for item resolution (
HN_CONCURRENCY_LIMIT)HTML bodies stripped to plain text — entities decoded once, code blocks kept verbatim, each link rendered once as its full URL — while titles, which are not HTML though some carry entities, are entity-decoded and never tag-stripped
Server-level
instructionsforwarded to LLM clients oninitialize— item types, ID reuse across tools, case-sensitive usernames, field sparsityNo API keys required — both upstream APIs are public; every request identifies itself with a
User-Agentofhn-mcp-server/<version>and the repository URL
Agent-friendly output:
Graceful partial failure — an item whose fetch fails after retries is reported by ID in
failedIds, apart from deleted, dead, or nonexistent items, rather than silently shrinking the result; eachhn_get_thread,hn_get_stories, andhn_get_usercall runs under one 50-second time budget, so hung fetches cannot hold it past an MCP client's 60-second timeout;hn_get_threadcounts the deleted and dead comments it drops, andhn_get_storiesandhn_get_userthe deleted, dead, and missing items, innotice; a rate-limited item stops the batch instead of sending every remaining item through its own retry ladderDiscriminated output contracts — typed error reasons (
item_not_found,upstream_rate_limited,upstream_html, …) with per-reason recovery text (a rate limit passes on the upstream'sRetry-AfterasretryAfter), and adepth/parentIdpair on every comment so callers reconstruct the tree without guessing nestingPagination provenance — every paged listing echoes the offset it used (
offset,submissionOffset,page) plus the exact next-offset value innotice,hn_search_contentalso echoes thecriteriait searched with, andhn_get_threadreturns a self-containednextCursor, so an agent can resume without recomputing stateResponse shaping — HTML stripping, URL normalization, and domain extraction remove upstream markup noise;
hn_search_content'sview: "compact"drops the two body-text fields that otherwise duplicate a hit's full textFenced upstream text — in
content[], every line of a body is block-quoted and titles are escaped only where they could break the surrounding Markdown, so a comment cannot pass for a server-authored line
Getting started
Public Hosted Instance
A public instance is available at https://hn.caseyjhand.com/mcp — no installation required. Point any MCP client at it via Streamable HTTP:
{
"mcpServers": {
"hn-mcp-server": {
"type": "streamable-http",
"url": "https://hn.caseyjhand.com/mcp"
}
}
}Self-Hosted / Local
Add to your MCP client configuration file:
{
"mcpServers": {
"hn-mcp-server": {
"type": "stdio",
"command": "bunx",
"args": ["@cyanheads/hn-mcp-server@latest"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}Or with npx (no Bun required):
{
"mcpServers": {
"hn-mcp-server": {
"type": "stdio",
"command": "npx",
"args": ["-y", "@cyanheads/hn-mcp-server"],
"env": {
"MCP_TRANSPORT_TYPE": "stdio",
"MCP_LOG_LEVEL": "info"
}
}
}
}Or with Docker:
{
"mcpServers": {
"hn-mcp-server": {
"type": "stdio",
"command": "docker",
"args": [
"run", "-i", "--rm",
"-e", "MCP_TRANSPORT_TYPE=stdio",
"ghcr.io/cyanheads/hn-mcp-server:latest"
]
}
}
}Prerequisites
Bun v1.4.4 or higher (or Node.js >= 24)
Installation
git clone https://github.com/cyanheads/hn-mcp-server.git
cd hn-mcp-server
bun installConfiguration
All configuration is via environment variables. No API keys required — HN APIs are public.
Variable | Description | Default |
| Max concurrent HTTP requests for batch item fetches (integer, 1–50). |
|
| Transport: |
|
| HTTP server port. |
|
| HTTP server host. |
|
| HTTP session handling: |
|
| Log level: |
|
| Directory for log files (Node.js only). |
|
See .env.example for the full list of optional overrides.
Running the server
Local development
Dev mode (auto-reload):
MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts # stdio MCP_TRANSPORT_TYPE=http bun --watch src/index.ts # HTTPBuild and run:
bun run rebuild bun run start:stdio # or start:httpRun checks and tests:
bun run devcheck # Lint, format, typecheck, security bun run test # Vitest test suite
Docker
docker build -t hn-mcp-server .
docker run --rm -p 3010:3010 hn-mcp-serverThe Dockerfile defaults to HTTP transport, stateless session mode, and logs to /var/log/hn-mcp-server. OpenTelemetry peer dependencies are installed by default — build with --build-arg OTEL_ENABLED=false to omit them.
Project structure
Directory | Purpose |
|
|
| Server-specific environment variable parsing and validation with Zod. |
| Tool definitions ( |
| HN Firebase + Algolia API client and domain types. |
| Unit and integration tests mirroring |
Development guide
See CLAUDE.md for development guidelines and architectural rules. The short version:
Handlers throw, framework catches — no
try/catchin tool logicUse
ctx.logfor request-scoped loggingAll tools are read-only — no auth scopes required
Wrap external API calls: validate raw → normalize to domain type → return output schema; never fabricate missing fields
Contributing
Issues are welcome. Run checks before submitting:
bun run devcheck
bun run testLicense
Apache-2.0 — see LICENSE for details.
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
This server cannot be deployed
Maintenance
Related MCP Connectors
Hacker News MCP — search and retrieve stories from Hacker News
Dive into the latest and greatest from the tech world with our Hacker News MCP server.
Deterministic Hacker News developer sentiment, themes & feature requests via MCP. No API key.
Related MCP Servers
- AlicenseAqualityDmaintenanceA Model Context Protocol (MCP) server that provides tools for searching and fetching information from Hacker News.476MIT
- AlicenseAqualityCmaintenanceMCP server for Hacker News that enables AI agents to search stories, read comments, and track tech trends via the public Hacker News API and Algolia HN Search.1014 npm4MIT
- AlicenseAqualityBmaintenanceMCP server enabling AI agents to interact with Hacker News, including fetching full comment trees with depth control, searching stories and comments, and retrieving user profiles.65MIT
- AlicenseAqualityFmaintenanceA read-only MCP server that enables browsing stories, reading comments, searching posts, and viewing user profiles on Hacker News.61MIT