@cyanheads/hn-mcp-server

<div align="center"> <h1>@cyanheads/hn-mcp-server</h1> <p><b>MCP server for Hacker News — feeds, threads, users, and search via Firebase and Algolia APIs</b> <div>4 Tools</div> </p> </div>

<div align="center">

</div>

<div align="center">

</div>

<div align="center">

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

</div>

---

Tools

Four read-only tools for accessing Hacker News data:

Tool Name	Description
hn_get_stories	Fetch stories from an HN feed (top, new, best, ask, show, jobs) with pagination.
hn_get_thread	Get an item and its comment tree as a threaded discussion with depth/count controls.
hn_get_user	Fetch a user profile with karma, about, and optionally their recent submissions.
hn_search_content	Search stories and comments via Algolia with type, author, date, and score filters.

hn_get_stories

Fetch stories from any HN feed with pagination support.

• Six feed types: top, new, best, ask, show, jobs
• Configurable count (1–100, default 30) and offset for pagination
• Returns enriched story objects with title, URL, score, author, comment count, and body text

---

hn_get_thread

Retrieve an item and its full comment tree via ranked breadth-first traversal.

• Depth control (0–10, default 3) — depth 0 doubles as a single-item lookup
• Comment limit (1–200, default 50) caps total comments across all levels
• Breadth-first traversal preserves HN's ranking order
• Flat comment list with depth/parentId for tree reconstruction

---

hn_get_user

Fetch a user profile with optional recent submission resolution.

• Profile includes karma, creation date, and about text (HTML stripped)
• Optionally resolves up to 50 most recent submissions into full items
• Submission resolution filters out dead/deleted items

---

hn_search_content

Full-text search via the Algolia HN Search API.

• Filter by content type: story, comment, ask_hn, show_hn, front_page
• Filter by author, date range (ISO 8601), and minimum points
• Sort by relevance or date
• Pagination with page/count controls

Features

Built on @cyanheads/mcp-ts-core:

• Declarative tool definitions — single file per tool, framework handles registration and validation
• Unified error handling across all tools
• Structured logging with request correlation
• Runs locally (stdio/HTTP) from the same codebase

HN-specific:

• Server-level instructions orientation forwarded to LLM clients on initialize — item types, ID reuse across tools, case-sensitive usernames, and field sparsity expectations
• Concurrent batch fetching with configurable parallelism for item resolution
• HTML entity decoding and tag stripping with code block and link preservation
• No API keys required — HN APIs are public

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": {
      "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.3.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 (1–50).	10
MCP_TRANSPORT_TYPE	Transport: stdio or http.	stdio
MCP_HTTP_PORT	HTTP server port.	3010
MCP_HTTP_HOST	HTTP server host.	localhost
MCP_LOG_LEVEL	Log level: debug, info, notice, warning, error.	info
LOGS_DIR	Directory for log files (Node.js only).	<project-root>/logs

Running the Server

Local Development

MCP_TRANSPORT_TYPE=stdio bun --watch src/index.ts   # Dev mode (stdio, auto-reload)
MCP_TRANSPORT_TYPE=http bun --watch src/index.ts    # Dev mode (HTTP, auto-reload)
bun run test                                         # Run test suite
bun run devcheck                                     # Lint + format + typecheck + audit

Production

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

Docker

docker build -t hn-mcp-server .
docker run -p 3010:3010 hn-mcp-server

Project Structure

Directory	Purpose
src/index.ts	createApp() entry point.
src/config/	Server-specific env var parsing with Zod.
src/services/hn/	HN Firebase + Algolia API client and domain types.
src/mcp-server/tools/definitions/	Tool definitions (*.tool.ts).

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

Contributing

Issues and pull requests are welcome. Run checks before submitting:

bun run devcheck
bun run test

License

Apache-2.0 — see LICENSE for details.