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

[![npm version](https://img.shields.io/npm/v/hn-mcp.svg)](https://www.npmjs.com/package/hn-mcp)
[![npm downloads](https://img.shields.io/npm/dm/hn-mcp.svg)](https://www.npmjs.com/package/hn-mcp)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](https://opensource.org/licenses/MIT)
[![Docker Pulls](https://img.shields.io/docker/pulls/karanb192/hn-mcp)](https://hub.docker.com/r/karanb192/hn-mcp)
[![GitHub stars](https://img.shields.io/github/stars/karanb192/hn-mcp?style=social)](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.