@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

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 a page of their 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 submission resolution.

Profile includes karma, creation date, and about text (HTML stripped)
Optionally resolves submissions into full items, up to 50 per page
submissionOffset pages through a long history; enrichment echoes the applied offset and the offset to request next
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
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

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:

config.json

{
  "mcpServers": {
    "hn-mcp-server": {
      "type": "streamable-http",
      "url": "https://hn.caseyjhand.com/mcp"
    }
  }
}

Self-Hosted / Local

Add to your MCP client configuration file:

config.json

{
  "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):

config.json

{
  "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:

config.json

{
  "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 (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.	`localhost`
`MCP_SESSION_MODE`	HTTP session handling: `auto`, `stateful`, or `stateless`. `auto` resolves to `stateful`. The published Docker image and `.env.example` pin `stateless`.	`auto`
`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

Terminal

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.