<img src="assets/hn-mcp-icon-white-background.png" width="48" align="center"/> HN-MCP

Hacker News Browser for Claude Desktop and AI Assistants

A Model Context Protocol (MCP) server that enables Claude Desktop and other AI assistants to browse Hacker News, search discussions, and analyze tech trends. Clean, fast, and actually works - no API keys required.

Table of Contents

• What makes HN-MCP different?
• Quick Start
• What can it do?
• Available Tools
• Installation Options
• Troubleshooting
• Development
• Support

What makes HN-MCP different?

• 🚀 Zero setup - Works instantly! Unlike Reddit, Twitter, or other platforms, Hacker News API requires no authentication, no API keys, no registration. Just install and go.
• ⚡ Smart caching - 50MB LRU cache with adaptive TTLs delivers 50ms cached responses (vs 200-500ms uncached). Popular content stays cached longer automatically.
• 🎯 Clean data - Direct from HN's Firebase API and Algolia Search. No fake metrics, no made-up sentiment scores, no hallucinated data.
• 🧠 LLM-optimized - Response formats designed specifically for AI assistants. Structured JSON that Claude can parse perfectly every time.
• 📦 TypeScript - 100% TypeScript with strict typing. Zod schemas validate every input and output. Reliable and maintainable.
• ✅ Multi-channel distribution - Available via npm, Docker Hub, MCP Registry, and .mcpb extension. Choose your preferred installation method.
• 🐳 Docker ready - Multi-platform images (amd64, arm64) with health checks and optimized builds. Deploy anywhere in seconds.

Quick Start (30 seconds)

For Claude Desktop

Add this to your claude_desktop_config.json:

{
  "mcpServers": {
    "hn": {
      "command": "npx",
      "args": ["hn-mcp"]
    }
  }
}

That's it! HN-MCP is now available in Claude.

What can it do?

Ask your AI assistant to:

• 📊 "What's trending on Hacker News?" - Browse top stories
• 🔍 "Search for discussions about AI" - Search across all content
• 💬 "Get comments on story 12345678" - Fetch full discussion threads
• 👤 "Analyze user pg" - Get user karma, submissions, and activity
• 📚 "Explain HN karma" - Understand Hacker News terminology

Perfect for:

• 🚀 Startup founders - Monitor YC companies, track competitor launches, discover market trends
• 💼 Tech recruiters - Find talented developers, understand the tech community pulse
• 📊 Market researchers - Analyze tech sentiment, identify emerging technologies, track discussion trends
• ✍️ Content creators - Find trending topics, research technical subjects, engage with developer community
• 🔍 Developers - Stay updated on latest tools, frameworks, and best practices discussed by peers
• 📰 Tech journalists - Source breaking stories, find expert opinions, track industry discussions
• 🎓 Researchers - Analyze tech community behavior, study information diffusion, collect discussion data

Available Tools

browse_stories

Browse posts from Hacker News by category.

- Types: top, new, best, ask (Ask HN), show (Show HN), job
- Limit: 1-100 stories (default: 30)
- Returns: Title, score, author, comments, URL

search_hn

Search across all Hacker News content.

- Query: Your search terms
- Filter by: Type, date range, author
- Sort by: relevance or date
- Uses: Algolia's HN Search API

get_story_details

Get a story with all its comments.

- Input: Story ID
- Returns: Full story + nested comment threads
- Options: Max comments, thread depth

user_analysis

Analyze a Hacker News user's profile.

- Username: Any HN user
- Returns: Karma, account age, recent submissions
- Insights: Activity patterns, top posts

hn_explain

Get explanations of HN terms.

- Terms: karma, flagged, dupe, Show HN, Ask HN, etc.
- Returns: Definition + context

Installation Options

Claude Desktop Extension (.mcpb)

Easiest method - One-click install for Claude Desktop:

1. Download hn-mcp.mcpb from latest release
2. Open Claude Desktop
3. Click on the extension file to install
4. Restart Claude Desktop

That's it! HN-MCP will be available immediately.

Quick Start with npx

# Claude Desktop - add to config (see Quick Start above)
npx hn-mcp

# HTTP mode for testing
HN_MCP_HTTP=true npx hn-mcp

Global Install

npm install -g hn-mcp
hn-mcp  # Run in stdio mode
HN_MCP_HTTP=true hn-mcp  # Run in HTTP mode

Using Docker

# Quick start - HTTP mode for API access
docker run -e HN_MCP_HTTP=true -p 3000:3000 karanb192/hn-mcp:latest

# stdio mode for development
docker run -it karanb192/hn-mcp:latest

# With docker-compose
docker-compose up

From Source

git clone https://github.com/karanb192/hn-mcp.git
cd hn-mcp
npm install
npm run build
npm link

Rate Limits

API	Official Limit	Our Limit	Notes
HN Firebase	None ✅	300/min	Self-imposed for courtesy
Algolia Search	None ✅	300/min	Max 1000 results per query

Why HN-MCP?

What others do wrong:

• ❌ Scoped npm names - @someone/hn-something is hard to remember
• ❌ Not published to npm - Manual installation only
• ❌ No caching - Slow repeated requests
• ❌ Poor documentation - Unclear how to use

What we do right:

• ✅ Clean package name - Just hn-mcp
• ✅ Smart caching - 50MB LRU cache with adaptive TTLs
• ✅ Clear documentation - You're reading it
• ✅ TypeScript - Type-safe and maintainable

Examples

Your AI can now answer:

"What are the top posts about GPT-4 today?"

→ search_hn with query="GPT-4", dateRange="last24h", sortBy="relevance"

"Show me what's trending on Hacker News"

→ browse_stories with type="top", limit=10

"What are people saying about this article?"

→ search_hn with the article URL to find discussions

"Analyze the user dang"

→ user_analysis with username="dang"

"Get the comments from HN story 12345678"

→ get_story_details with id="12345678"

Troubleshooting

Common Issues

"Command not found" error

# Ensure npm is installed
node --version
npm --version

# Try with full npx path
$(npm bin -g)/hn-mcp

Connection issues

• Hacker News may be down (check https://status.ycombinator.com)
• Firewall blocking requests
• Try restarting the MCP server

Search returns max 1000 results

• This is Algolia's hard limit
• Use date filters to narrow results
• Try more specific search queries

Environment Variables

Configure HN-MCP using environment variables. See .env.example for detailed documentation.

Variable	Description	Default
HN_MCP_HTTP	Run as HTTP server instead of stdio	false
HN_MCP_PORT	HTTP server port	3000
HN_MCP_NO_CACHE	Disable caching for real-time data	false
HN_MCP_RATE_LIMIT	Override rate limit (requests/minute)	300

Quick setup:

# Copy example file
cp .env.example .env

# Edit with your preferences
nano .env

Development

# Install dependencies
npm install

# Run in development
npm run dev

# Build
npm run build

# Run tests
npm run typecheck

# Deploy locally
./deploy-server.sh       # Port 3000
./deploy-server.sh -p 8080  # Custom port

# Docker build
docker build -t karanb192/hn-mcp .
docker run -e HN_MCP_HTTP=true -p 3000:3000 karanb192/hn-mcp

# Docker development with hot reload
docker-compose --profile dev up

Requirements

• Node.js >= 18.0.0
• npm or yarn
• TypeScript 5.5+

Contributing

PRs welcome! See CONTRIBUTING.md for guidelines.

We keep things simple:

• Clean TypeScript code
• Smart caching
• Clear documentation
• Fast responses

Support

• 🐛 Report bugs
• 💡 Request features
• ⭐ Star on GitHub

License

MIT - Use it however you want!

---

Made with ❤️ for the MCP community by the creator of reddit-mcp-buddy. No venture capital, no tracking, just a good MCP server.