A small, read-only Model Context Protocol server that gives Claude Desktop and Claude Code first-class access to Hacker News. It speaks MCP over stdio and talks to two public, no-auth APIs:
Official HN (Firebase)—https://hacker-news.firebaseio.com/v0/
— feeds, items, and users.Algolia HN Search—https://hn.algolia.com/api/v1/
— full-text search.
No API keys, no accounts, nothing is mutated. Every tool is marked read-only.
| Tool | When to reach for it |
|---|---|
get_stories |
|
Browse a ranked feed. Returns a compact list (id, title, author, score, comment count, url, hn_url ) with no comment trees — ideal for scanning the front page or a section. Params: category (top /new /best /ask /show /job , default top ), limit (default 30, max 100). |
|
get_item |
|
Go deep on one thread. Returns the item plus a nested comment tree walked breadth-first. The tree is hard-capped by max_comments (default 50) and max_depth (default 3) so it never blows up your context; a truncation_note tells you when replies were cut. Dead/deleted comments are skipped. Params: id (required), include_comments (default true), max_depth (default 3), max_comments (default 50). |
|
get_user |
|
Look up a profile by username (case-sensitive). Returns karma, the about text, account creation date, and submitted-item count. Param: id (required). |
|
search |
|
Full-text search across all of HN via Algolia. Params: query (required), sort (relevance default, or date ), tags (e.g. story , comment , ask_hn , show_hn , front_page ), min_points (int), limit (default 20, max 100). Returns hits with title, author, points, comment count, date, story URL, and hn_url . |
Two conventions across all tools: every Unix timestamp is returned both raw (time
) and as an ISO 8601
UTC string (time_iso
), and every item carries a derived hn_url
(https://news.ycombinator.com/item?id=<id>
).
Quick rule of thumb: get_stories
/search
to find things, get_item
to read one thing in depth.
Requires a recent stable Rust toolchain (edition 2021).
git clone https://github.com/devrelopers/hackernews-mcp
cd hackernews-mcp
cargo build --release
The binary lands at target/release/hackernews-mcp
.
Add an entry to your claude_desktop_config.json
:
macOS:~/Library/Application Support/Claude/claude_desktop_config.json
Windows:%APPDATA%\Claude\claude_desktop_config.json
{
"mcpServers": {
"hackernews": {
"command": "/absolute/path/to/hackernews-mcp/target/release/hackernews-mcp"
}
}
}
Use the absolute path to the binary you just built (e.g.
/Users/you/hackernews-mcp/target/release/hackernews-mcp
). Restart Claude Desktop; the four tools will appear under the 🔌 tools menu.
claude mcp add hackernews -- /absolute/path/to/hackernews-mcp/target/release/hackernews-mcp
- Item fetches in
get_stories
andget_item
run concurrently with a politeness cap of ~10 in-flight requests. - Logs are written to
stderr so they never corrupt the JSON-RPC stream on stdout. SetRUST_LOG=debug
for verbose tracing. - Missing items/users return an actionable error
(
Item <id> not found — it may be deleted or the ID may be invalid.
) rather than a panic.
src/
main.rs # tokio entrypoint + stdio transport wiring
client.rs # shared reqwest client over the Firebase + Algolia APIs
tools.rs # the four MCP tools + breadth-first comment-tree walker
types.rs # data models and compact output shapes
MIT — see LICENSE.