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.
- What makes HN-MCP different?
- Quick Start
- What can it do?
- Available Tools
- Installation Options
- Troubleshooting
- Development
- Support
- 🚀 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.
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.
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
- 🚀 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
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 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 a story with all its comments.
- Input: Story ID
- Returns: Full story + nested comment threads
- Options: Max comments, thread depth
Analyze a Hacker News user's profile.
- Username: Any HN user
- Returns: Karma, account age, recent submissions
- Insights: Activity patterns, top posts
Get explanations of HN terms.
- Terms: karma, flagged, dupe, Show HN, Ask HN, etc.
- Returns: Definition + context
Easiest method - One-click install for Claude Desktop:
- Download
hn-mcp.mcpbfrom latest release - Open Claude Desktop
- Click on the extension file to install
- Restart Claude Desktop
That's it! HN-MCP will be available immediately.
# Claude Desktop - add to config (see Quick Start above)
npx hn-mcp
# HTTP mode for testing
HN_MCP_HTTP=true npx hn-mcpnpm install -g hn-mcp
hn-mcp # Run in stdio mode
HN_MCP_HTTP=true hn-mcp # Run in HTTP mode# 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 upgit clone https://github.com/karanb192/hn-mcp.git
cd hn-mcp
npm install
npm run build
npm link| 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 |
- ❌ Scoped npm names -
@someone/hn-somethingis hard to remember - ❌ Not published to npm - Manual installation only
- ❌ No caching - Slow repeated requests
- ❌ Poor documentation - Unclear how to use
- ✅ 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
"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"
"Command not found" error
# Ensure npm is installed
node --version
npm --version
# Try with full npx path
$(npm bin -g)/hn-mcpConnection 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
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# 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- Node.js >= 18.0.0
- npm or yarn
- TypeScript 5.5+
PRs welcome! See CONTRIBUTING.md for guidelines.
We keep things simple:
- Clean TypeScript code
- Smart caching
- Clear documentation
- Fast responses
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.