hn-mcp-server

<div align="center"> <h1>@cyanheads/hn-mcp-server</h1> <p><b>Browse Hacker News feeds, threads, and user profiles with full-text search via MCP. STDIO or Streamable HTTP.</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 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:

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

| 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_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.