io.github.cyanheads/hn-mcp-server

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

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

• 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 config (e.g., claude_desktop_config.json):

{
  "mcpServers": {
    "hn-mcp-server": {
      "type": "stdio",
      "command": "bunx",
      "args": ["@cyanheads/hn-mcp-server@latest"]
    }
  }
}

Or with npx:

{
  "mcpServers": {
    "hn-mcp-server": {
      "type": "stdio",
      "command": "npx",
      "args": ["-y", "@cyanheads/hn-mcp-server"]
    }
  }
}

Prerequisites

• Bun v1.2.0 or higher (or Node.js >= 22)

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

bun run dev:stdio       # Dev mode (stdio, auto-reload)
bun run dev:http        # 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.