hn

HN-MCP is a Model Context Protocol server that exposes Hacker News browsing and analysis capabilities to Claude Desktop and other AI assistants without requiring API keys. It provides structured, queryable access to top stories, search across discussions, fetch full story threads, analyze user profiles, and explain common HN terms. You can invoke tools like browse_stories to browse posts by category, search_hn to query discussions, get_story_details to fetch a story with comments, user_analysis to inspect a user’s activity, and hn_explain to get definitions for HN terminology. Use the Quick Start example to enable it in Claude Desktop or your own MCP client, and customize how the server runs via environment variables such as HTTP mode and port. The server emphasizes caching, type-safe responses, and a clean JSON interface suitable for automation and AI agents.

Prerequisites:

• Node.js (LTS version) and npm installed on your machine
• Git
• Optional: Docker if you prefer containerization

Install from npm (recommended for quick setup):

1. Ensure Node.js and npm are installed:

   node --version npm --version

2. Install the package globally (optional) and start the MCP server in stdio mode:

   npm install -g hn-mcp hn-mcp

3. Alternatively, run with npx (no permanent install):

   npx hn-mcp

If you want HTTP mode (for API access), set HN_MCP_HTTP=true when starting the server:

HN_MCP_HTTP=true npx hn-mcp

Using Docker:

1. Quick start (HTTP mode):

   docker run -e HN_MCP_HTTP=true -p 3000:3000 karanb192/hn-mcp:latest

2. Stdio mode (development):

   docker run -it karanb192/hn-mcp:latest

3. Docker Compose example (HTTP):

   version: '3' services: hn-mcp: image: karanb192/hn-mcp:latest ports: - "3000:3000" environment: - HN_MCP_HTTP=true

Tips and notes:

• Environment variables: HN_MCP_HTTP (true to run HTTP API server), HN_MCP_PORT (port for HTTP server, default 3000), HN_MCP_NO_CACHE (disable caching), and HN_MCP_RATE_LIMIT (override requests/minute).
• The MCP outputs are structured JSON designed for AI assistants; integrate them into prompts or pipelines accordingly.
• If you encounter connection or rate-limit issues, verify network access to Hacker News endpoints and consider enabling caching or adjusting rate limits.
• For Docker users, ensure the image supports multi-arch platforms (amd64, arm64) and check health status endpoints if provided by the container.
• The repository supports multiple installation methods (CLI, Docker, Claude Desktop extension). Choose the method that best fits your workflow.
• No API keys are required for Hacker News access through this MCP server as described in the documentation.