Skip to main content
Glama
karanb192

HN-MCP

by karanb192
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Remote

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.

npm version npm downloads License: MIT Docker Pulls GitHub stars

Table of Contents

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

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

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.

This server cannot be installed

-
security - not tested
A
license - permissive license
-
quality - not tested

How are these scores calculated?

Resources

New MCP Servers

Latest Blog Posts

MCP directory API

We provide all the information about MCP servers via our MCP API.

curl -X GET 'https://glama.ai/api/mcp/v1/servers/karanb192/hn-mcp'

If you have feedback or need assistance with the MCP directory API, please join our Discord server