necl-hn-mcp
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@necl-hn-mcp Show me the top 10 stories from the last 24 hours"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
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 |
| Top N stories from the last N hours, ranked by score. Default: top 10 from last 24h. |
| Full story metadata: title, url, score, author, comments count, posted time. |
| Top-level comments thread for a story, sorted by HN ranking. |
| Full-text search across HN posts and comments (via Algolia HN API). |
| Stories from a specific category: |
Related MCP server: HackerNews MCP Server
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):
{
"mcpServers": {
"necl-hn": {
"command": "uvx",
"args": [
"--from",
"git+https://github.com/adjacentai/necl-hn-mcp.git",
"necl-hn-mcp"
]
}
}
}Don't have uvx? Install it: pip install uv or brew install uv.
Via pip + python -m
pip install git+https://github.com/adjacentai/necl-hn-mcp.gitThen in mcp.json:
{
"mcpServers": {
"necl-hn": {
"command": "python",
"args": ["-m", "necl_hn_mcp"]
}
}
}From source (for development)
git clone https://github.com/adjacentai/necl-hn-mcp.git
cd necl-hn-mcp
pip install -e ".[dev]"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
newandbestcategories 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
showcategory 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.
Tool calls timeout.
HN's Firebase API can be slow when fetching many items (e.g. hn_top_stories(limit=30, hours=168) scans 200 stories). Default timeout is 10s per request. For long-window queries, use lower limit.
Algolia returns no hits.
Algolia indexes HN content with a delay (~5-15 min for fresh items). Try sort="date" for recent activity.
Comments thread is empty for a story I see on HN.
hn_get_comments returns only top-level comments. Replies aren't recursively fetched (to keep token cost predictable for LLMs). Use the replies_count field on each comment to know if there's deeper discussion.
Tools don't show up in Claude.
After editing mcp.json, fully restart Claude Desktop / Claude Code (not just reload). Check the MCP logs in Settings → Developer.
Pair with
necl-content-poster Skill — turn HN stories into ready-to-publish posts for TG/LinkedIn/Threads.
Full pipeline:
necl-hn-mcp (find story) → necl-content-poster (write 3 posts) → you publishBuilt by NeCL
neclco.com — production AI engineering. RAG systems, voice agents, Telegram bots, custom MCPs and content engines for companies that need more than wrappers.
Need a custom MCP wired to your internal APIs / databases / SaaS? Visit neclco.com.
Development
git clone https://github.com/adjacentai/necl-hn-mcp.git
cd necl-hn-mcp
pip install -e ".[dev]"
# Run locally with MCP inspector
mcp dev src/necl_hn_mcp/server.pyLicense
MIT — see LICENSE.
Available Tools
5 toolshn_categoryA
Get stories from a specific HN category.
Args: category: One of "top", "new", "best", "ask", "show", "job". limit: Number of stories to return (1-30). Default 10.
Returns: List of story dicts.
Inputs: limit, category. Returns: result
hn_get_commentsA
Get the top-level comments thread for a story, in HN ranking order.
Args: story_id: The HN item id of the parent story. limit: Number of comments to return (1-30). Default 10.
Returns: List of comment dicts with id, author, text, posted_unix, replies_count.
Inputs: story_id (required), limit. Returns: result
hn_get_storyA
Get full metadata for a single HN story by id.
Args: story_id: The HN item id.
Returns: Story dict with id, title, url, score, author, comments_count, posted_unix, hn_url, type, text. Returns {"error": "..."} if not found.
Inputs: story_id (required).
hn_searchA
Full-text search across HN stories and comments via Algolia.
Args: query: Search query string. sort: "relevance" (default) or "date" (newest first). limit: Number of hits to return (1-50). Default 20.
Returns:
Dict with hits (list of clean dicts: id, kind, title, url, hn_url,
author, points, comments_count, story_text, comment_text, created_at, tags)
and total_hits (total matches Algolia found, may exceed limit).
Inputs: query (required), sort, limit.
hn_top_storiesA
Get the top Hacker News stories from the last N hours, ranked by score.
Args: limit: Number of stories to return (1-30). Default 10. hours: Time window in hours back from now. Default 24.
Returns: List of story dicts with id, title, url, score, author, comments_count, posted_unix, hn_url, type, text (for Ask/Show HN posts).
Inputs: hours, limit. Returns: result
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelog…
TDQS
Scored across 5 tools
Each tool has a clearly distinct purpose: retrieving stories by category, by time window, by search, a single story by ID, and comments for a story. No overlap or ambiguity.
All tools follow the `hn_` prefix with a consistent verb_noun pattern in snake_case (e.g., hn_category, hn_get_story, hn_search). No mixing of conventions.
Five tools cover the main read operations for Hacker News without being too few or too many. Each tool serves a necessary function in the domain.
Covers story retrieval, search, detail, and comments well. Missing user info or nested replies, but these are minor gaps for typical HN consumption use cases.
Maintenance
Related MCP Connectors
Browse Hacker News feeds, threads, and user profiles with full-text search.
Hacker News stories, search and Who is Hiring jobs via the official API. Runs on Apify.
Browse Hacker News from chat: top stories, search, read comment threads, and post or upvote when yo…
Hacker News front page and search: stories, points, comments, and which stories link to your domain.
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to search, retrieve, and interact with HackerNews content including stories, comments, polls, and user information. Provides comprehensive access to all HackerNews API endpoints with 15 specialized tools for content discovery and analysis.1560 npm5MIT
- AlicenseAqualityDmaintenanceProvides programmatic access to Hacker News content via the HN Algolia API. It enables AI assistants to search stories, retrieve comments, access user profiles, and explore the front page in real-time.960 npmMIT
- FlicenseAqualityDmaintenanceEnables AI assistants to read and search Hacker News for top stories, comments, user profiles, and job listings using the Firebase and Algolia APIs. It facilitates natural language research into community discussions and technological trends across the HN platform.8-
- AlicenseNot gradedqualityDmaintenanceProvides AI agents with Hacker News data including front-page lists, full-text search via Algolia, and recent Show HN launches.MIT