adjacentai/necl-hn-mcp

> **Hacker News tools for AI agents.** Top stories, story details, comments thread, full-text search.
>
> **Zero credentials.** Public HN API. Install and use.
Built by NeCL — AI engineering studio. Production-tested: this is the exact HN layer that powers our internal content agent, running 3× daily for months.
Tools
| Tool | What it does |
|---|---|
| hn_top_stories(limit, hours) | Top N stories from the last N hours, ranked by score. Default: top 10 from last 24h. |
| hn_get_story(id) | Full story metadata: title, url, score, author, comments count, posted time. |
| hn_get_comments(id, limit) | Top-level comments thread for a story, sorted by HN ranking. |
| hn_search(query, sort) | Full-text search across HN posts and comments (via Algolia HN API). |
| hn_category(category, limit) | Stories from a specific category: top, new, best, ask, show, job. |
Why this MCP
- **Zero credentials, zero config** — public HN API, no rate limits worth worrying about, no signup.
- **Battle-tested code** — extracted from our internal HN-to-drafts content engine that's been running 3×/day for months.
- **Built for AI agents** — every tool returns clean structured data that LLMs can chain together (search → top story → comments → summary).
- **Use case** — content research, trend monitoring, automatic news digests, prompt-context enrichment.
Install
Via uvx (recommended — no setup)
uvx runs the package in an ephemeral env. No pip install, no venv. Add to your mcp.json (Claude Desktop, Claude Code, or any MCP client):
Don't have uvx? Install it: pip install uv or brew install uv.
Via pip + python -m
Then in mcp.json:
From source (for development)
Then use the same python -m necl_hn_mcp config as above.
Example use in Claude
Once installed, just ask Claude things like:
- "What are the top 5 stories on HN in the last 6 hours?"
- "Get the comments thread for HN story 38420000"
- "Search HN for posts about RAG performance, sorted by date"
- "Show me everything in the Ask HN category right now"
- "Find the top 3 Show HN posts about AI agents this week"
Claude will call the right tool, no further setup.
What you can build with this
- **Daily content brief** — pull top HN stories, summarize, generate cross-platform posts.
- **Competitive research bot** — search HN for mentions of your competitors, surface negative comments.
- **Trend detector** — monitor new and best categories on a cron, alert when a topic spikes.
- **Newsletter pipeline** — search by keyword window, cluster results, generate editorial digest.
- **Customer-discovery agent** — search Ask HN for problems your product solves, generate cold-outreach drafts.
- **Tech-radar updater** — periodically scan show category for new tools in your stack.
Troubleshooting
**"mcp command not found" / install errors.**
Make sure your Python is 3.10+. If using uvx, ensure uv is installed (pip install uv). For pip install: pip install necl-hn-mcp then verify python -m necl_hn_mcp --help doesn't error.