hn-mcp-server

---

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
hn_get_stories	Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count
hn_get_thread	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
hn_get_user	Fetch a user profile with karma, about, and optionally a page of resolved submissions
hn_search_content	Search stories, comments, polls, and jobs via Algolia by keyword, by filters alone, or both — type, author, parent story, date range, and minimum points

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 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 text budget that cuts only between comments. 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, or an upstream rate limit 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 <author>, Poll option by <author> on poll <id> — 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, 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 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 are listed in failedIds with a notice naming the retry; a window where every submission failed returns the classified upstream error

---

hn_search_content _tool

• Free-text query 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
• 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
• 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 Algolia's 1,000-hit ceiling; the last page of such a search gets a notice naming the ceiling and narrower dateRange windows to reach the rest. While more pages remain, truncated is set and notice names the next page; a page past the end gets a notice naming the last valid page (or page: 0 past the ceiling)

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 instructions forwarded to LLM clients on initialize — item types, ID reuse across tools, case-sensitive usernames, field sparsity
• No API keys required — both upstream APIs are public

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; hn_get_thread also counts the deleted and dead comments it drops, and a rate-limited item stops the batch instead of sending every remaining item through its own retry ladder
• Discriminated 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's Retry-After as retryAfter), and a depth/parentId pair on every comment so callers reconstruct the tree without guessing nesting
• Pagination provenance — every paged listing echoes the offset it used (offset, submissionOffset, page) plus the exact next-offset value in notice, hn_search_content also echoes the criteria it searched with, and hn_get_thread returns a self-contained nextCursor, so an agent can resume without recomputing state
• Response shaping — HTML stripping, URL normalization, and domain extraction remove upstream markup noise; hn_search_content's view: "compact" drops the two body-text fields that otherwise duplicate a hit's full text
• Fenced 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.0 or higher (or Node.js >= 24)

Installation

git clone https://github.com/cyanheads/hn-mcp-server.git
cd hn-mcp-server
bun install

Configuration

All configuration is via environment variables. No API keys required — HN APIs are public.

Variable	Description	Default
HN_CONCURRENCY_LIMIT	Max concurrent HTTP requests for batch item fetches (integer, 1–50).	10
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	HTTP server port.	3010
MCP_HTTP_HOST	HTTP server host.	127.0.0.1
MCP_SESSION_MODE	HTTP session handling: stateful, stateless, or auto (resolves to stateful). The server declares stateless in source, and the published Docker image and .env.example set it too; a meaningful env value still overrides.	stateless
MCP_LOG_LEVEL	Log level: debug, info, notice, warning, error.	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs

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    # HTTP
  

• Build and run:

  bun run rebuild
  bun run start:stdio   # or start:http
  

• Run 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-server

The 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
src/index.ts	createApp() entry point — registers tools and inits the HN service.
src/config/	Server-specific environment variable parsing and validation with Zod.
src/mcp-server/tools/definitions/	Tool definitions (*.tool.ts).
src/services/hn/	HN Firebase + Algolia API client and domain types.
tests/	Unit and integration tests mirroring src/.

Development guide

See CLAUDE.md for development guidelines and architectural rules. The short version:

• Handlers throw, framework catches — no try/catch in tool logic
• Use ctx.log for request-scoped logging
• All 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 test

License

Apache-2.0 — see LICENSE for details.