hn-mcp-server

Tools

Four read-only tools for accessing Hacker News data:

`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:

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

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

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.