@cyanheads/hn-mcp-server

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

Overview

Feeds, threads, and profiles from the Hacker News Firebase API and Algolia Search API. Browse ranked feeds, read full comment threads, look up user profiles, and search stories and comments by type, author, date, or score. Runs as a stdio process, a local Streamable HTTP server, or the public hosted endpoint above.

Tools

Related MCP server: @isteam/hackernews-mcp

Capability reference

hn_get_stories tool

• Six feed types: top, new, best, ask, show, jobs; count (1–100, default 30) and offset for pagination

• 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, hasMore, and a notice explaining empty pages (empty feed, offset past end, or every item on the page deleted/flagged)

hn_get_thread tool

• itemId plus depth (0–10, default 3; 0 returns the item with no comments) and maxComments (1–200, default 50) capping the total across all levels

• Breadth-first traversal ranked like HN — top-ranked top-level comments resolve first, replies fill in only after the level above is exhausted

• Flat comment list carries depth/parentId for tree reconstruction, plus childCount and an isOp flag when the comment author matches the root item's author

• notice reports deleted/dead comments omitted during traversal and, when totalLoaded is below totalAvailable, the hint to raise maxComments/depth

hn_get_user tool

• username is case-sensitive and trimmed; includeSubmissions (default false) resolves recent submissions, with submissionCount (1–50, default 10) and submissionOffset paging through a long history

• Profile includes karma, creation date, and about text (HTML stripped); submissions filter out dead/deleted items

• Enrichment echoes submissionOffset and the offset to send next, or a notice when the requested offset is past the end of the history

hn_search_content tool

• Free-text query plus tags (story/comment/ask_hn/show_hn/front_page), author, dateRange (ISO 8601), and minPoints filters; sort by relevance or date; count (1–50, default 30) and page for pagination

• 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

• Highlight metadata (highlights.title, highlights.text, matchedWords) shows which terms matched and where

• Enrichment reports totalHits, page, and the actual reachable totalPages — not derived from totalHits, since broad queries report far more hits than Algolia will serve

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 entity decoding and tag stripping, preserving code blocks and links

• 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 — hn_get_thread counts deleted and dead comments dropped during traversal and surfaces the count in notice rather than silently shrinking the result; hn_get_stories and hn_get_user filter dead/deleted items the same way

• Discriminated output contracts — typed error reasons (item_not_found, upstream_rate_limited, upstream_html, …) with per-reason recovery text, and a depth/parentId pair on every comment so callers reconstruct the tree without guessing nesting

• Pagination provenance — every paged tool echoes the offset it used (offset, submissionOffset, page) plus the exact next-offset value in notice, so an agent can resume a listing 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

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.

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

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.