# <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)](https://modelcontextprotocol.io) 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.
[](https://www.npmjs.com/package/hn-mcp)
[](https://www.npmjs.com/package/hn-mcp)
[](https://opensource.org/licenses/MIT)
[](https://hub.docker.com/r/karanb192/hn-mcp)
[](https://github.com/karanb192/hn-mcp)
## Table of Contents
- [What makes HN-MCP different?](#what-makes-hn-mcp-different)
- [Quick Start](#quick-start-30-seconds)
- [What can it do?](#what-can-it-do)
- [Available Tools](#available-tools)
- [Installation Options](#installation-options)
- [Troubleshooting](#troubleshooting)
- [Development](#development)
- [Support](#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`:
```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](https://github.com/karanb192/hn-mcp/releases/latest)
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
```bash
# 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
```bash
npm install -g hn-mcp
hn-mcp # Run in stdio mode
HN_MCP_HTTP=true hn-mcp # Run in HTTP mode
```
### Using Docker
```bash
# 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
```bash
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**
```bash
# 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](.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:**
```bash
# Copy example file
cp .env.example .env
# Edit with your preferences
nano .env
```
## Development
```bash
# 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](CONTRIBUTING.md) for guidelines.
We keep things simple:
- Clean TypeScript code
- Smart caching
- Clear documentation
- Fast responses
## Support
- 🐛 [Report bugs](https://github.com/karanb192/hn-mcp/issues)
- 💡 [Request features](https://github.com/karanb192/hn-mcp/issues)
- ⭐ [Star on GitHub](https://github.com/karanb192/hn-mcp)
## License
MIT - Use it however you want!
---
Made with ❤️ for the MCP community by the creator of [reddit-mcp-buddy](https://github.com/karanb192/reddit-mcp-buddy). No venture capital, no tracking, just a good MCP server.
