How do I use unofficial-HackerNews-MCP-CLI?

1. Click on "Install Server". 2. Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state. 3. In the chat, type @ followed by the MCP server name and your instructions, e.g., "@unofficial-HackerNews-MCP-CLI show me the top 5 HackerNews stories" 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.

unofficial-HackerNews-MCP-CLI

by Riddhimaan-Senapati

Overview Schema Related Servers Score Discussions

Python

Remote

This project wraps the official HackerNews API behind a single shared async client and exposes it two ways:

hn, a Typer command-line client with Rich-formatted output.
hn-mcp, a FastMCP server that exposes the same operations as MCP tools for Claude and other MCP clients.

The API is read-only, needs no authentication, and has no rate limit.

Install

Requires Python 3.10+ and uv.

uv sync                    # create the venv and install
uv run hn top              # run the CLI without installing scripts
# or install the console scripts (hn, hn-mcp) into the environment:
uv pip install -e .

Related MCP server: Hacker News MCP Server

CLI

hn top                 # front-page (top) stories
hn top --limit 10      # -n 10
hn new                 # newest stories
hn best                # best recent stories
hn ask                 # latest Ask HN
hn show                # latest Show HN
hn jobs                # latest job postings

hn item 8863           # a single story/comment/job/poll
hn comments 8863       # threaded comment tree (--depth, --limit)
hn user pg             # a user's profile (case-sensitive name)

hn max-item            # id of the most recently created item
hn updates             # recently changed items and profiles

Add --json to any command to get raw JSON instead of a table, which is handy for scripting:

hn top -n 5 --json | jq -r '.[] | "\(.title) (\(.url // .hn_url))"'
hn user pg --json | jq .karma

Run hn --help for the full command list.

MCP server

Run over stdio, which is the transport MCP clients use by default:

hn-mcp

Or over HTTP:

hn-mcp --http --host 127.0.0.1 --port 8000

{
  "mcpServers": {
    "hackernews": { "command": "hn-mcp" }
  }
}

Tools

Tool	Description
`get_stories(category, limit)`	A list of stories; `category` is one of `top`, `new`, `best`, `ask`, `show`, `job`
`get_item(item_id)`	A single story, comment, job, or poll
`get_comments(item_id, max_depth, max_per_level)`	Threaded comment tree
`get_user(username)`	A user's public profile
`get_max_item_id()`	Id of the most recently created item
`get_updates()`	Items and profiles that changed most recently

Skill

skills/hackernews/SKILL.md is an agent skill that teaches Claude how and when to use the hn CLI and MCP server.

Project layout

src/hn/
  client.py   # shared async HackerNews API client (httpx)
  models.py   # Pydantic models for items and users
  server.py   # FastMCP server (hn-mcp)
  cli.py      # Typer CLI (hn)
skills/hackernews/SKILL.md
tests/        # pytest + respx (mocked API)

Development

uv run ruff check .          # lint
uv run ruff format --check . # formatting
uv run pytest                # test suite (API calls are mocked)

CI runs lint, formatting, and the test suite on Python 3.10 through 3.13 via GitHub Actions. See CONTRIBUTING.md for the full workflow.

License

MIT. See LICENSE. This is an unofficial project and is not affiliated with Hacker News or Y Combinator.

Available Tools

6 tools

get_commentsA

Get the threaded comment tree for an item.

Each comment includes a nested replies list bounded by max_depth and max_per_level. Comment text is HTML.

ParametersJSON Schema

Name	Required	Description
`item_id`	Yes	Id of the story or comment to expand.
`max_depth`	No	Reply nesting depth (0 = top-level comments only).
`max_per_level`	No	Max comments to expand per level.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.2/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description carries full burden. It discloses nesting behavior bounded by 'max_depth' and 'max_per_level', and that comment text is HTML. This provides useful behavioral context beyond the input schema.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two sentences, no fluff. Every word serves a purpose, front-loading the core action and key details.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Output schema exists, so return values are covered structurally. The description fills gaps by explaining the threaded nature and HTML content. Could mention pagination or max total comments, but sufficient for typical use.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so baseline is 3. The description adds value by explaining the nested replies structure and how parameters bound it, plus the HTML nature of text, going beyond parameter names and types.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description uses a specific verb 'Get' and resource 'threaded comment tree for an item', clearly differentiating from siblings like 'get_item' or 'get_stories' which fetch single items or top-level stories.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use this tool vs alternatives (e.g., 'get_item' for single item). Context is implied but not elaborated, leaving the agent to infer.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_itemA

Get a single HackerNews item (story, comment, job, poll, or poll option).

Returns null if no item exists with that id.

ParametersJSON Schema

Name	Required	Description	Default
`item_id`	Yes	The item's numeric id.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.1/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations provided, the description clearly states the return behavior (null if no item exists) and implies read-only operation via 'Get', but omits other potential behavioral traits like error handling or rate limits.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is extremely concise with two sentences, front-loaded with the purpose, and contains no unnecessary information.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given the simple nature of the tool and the presence of an output schema, the description sufficiently covers the core functionality and return behavior, making it complete for an agent to invoke correctly.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100%, so the description adds no additional meaning beyond the schema's description of item_id as a numeric id.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool retrieves a single HackerNews item, enumerates the item types (story, comment, job, poll, poll option), and distinguishes it from sibling tools that handle collections or different endpoints.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage for retrieving a single item by ID but provides no explicit guidance on when to use it versus siblings like get_stories or get_comments, nor any exclusions or alternative contexts.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_max_item_idA

Get the id of the most recently created item, useful for walking all items.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries the full burden. It notes the tool is read-only (getting an id), but does not disclose any other behavioral traits like rate limits, permissions, or whether the id is monotonically increasing. The description is straightforward but lacks depth.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

The description is a single, front-loaded sentence with no wasted words. It efficiently conveys the tool's purpose and a key use case.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given no parameters, the description is reasonably complete for a simple retrieval tool. It mentions a use case ('walking all items'), but could elaborate on how 'walking' works (e.g., using the returned id for further queries). Still, it is sufficient.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

There are no parameters, and schema description coverage is 100%. The description adds no parameter-specific meaning, but none is needed. Baseline 4 for zero parameters is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description explicitly states the tool retrieves the id of the most recently created item. It uses a specific verb ('Get') and resource ('max item id'), and distinguishes from sibling tools like 'get_item' or 'get_comments' by focusing on the highest id.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies a use case ('useful for walking all items'), suggesting it could be used to iterate through items. However, it does not explicitly state when to use or not use this tool, nor does it mention alternatives or prerequisites.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_storiesA

Get a list of HackerNews stories from a category, with full details.

'top', 'new' and 'best' draw from up to 500 stories; 'ask', 'show' and 'job' from up to 200. Each result includes title, url, score, author, comment count and the canonical HN discussion link.

ParametersJSON Schema

Name	Required	Description	Default
`limit`	No	How many stories to return (1-500).
`category`	No	Which list: top, new, best, ask, show, or job stories.	top

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4/5.0

Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description carries full burden. It discloses category-dependent size limits and returned fields, but omits read-only nature, rate limits, or potential errors. Adequate but not thorough.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Three concise sentences, no redundancy. First sentence states purpose, second adds nuance on limits, third enumerates output fields. Every sentence earns its place.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness4/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

With an output schema present, the description's listing of return fields is helpful but not necessary. It adequately covers the tool's behavior for a list-fetching operation, though it lacks details on error handling or prerequisites.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Input schema covers both parameters with descriptions (100% coverage). The description adds value by clarifying that limits vary by category (500 vs 200) and listing returned fields, which provides context beyond the schema.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

The description clearly states the verb 'Get' and the resource 'list of HackerNews stories', specifying the categories. It explicitly distinguishes the tool's scope and output details, leaving no doubt about its function.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines3/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

The description implies usage (when you need story lists by category) but provides no explicit guidance on when to use this tool versus alternatives like 'get_comments'. No exclusions or context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_updatesB

Get the items and user profiles that changed most recently.

ParametersJSON Schema

Name	Required	Description	Default
No parameters

Output Schema

ParametersJSON Schema

Name	Required	Description
No output parameters

TDQS

B3.2/5.0

Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

With no annotations, the description fails to disclose any behavioral traits such as rate limits, authentication needs, or data recency bounds. It only states the basic function.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Single sentence is highly concise and front-loaded. Every word is necessary; no redundancy.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness3/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Given low complexity and presence of output schema, the description is adequate but incomplete regarding time scope (e.g., 'most recently' is ambiguous) and expected return structure.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters4/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

No parameters exist; schema coverage is 100% by default. Description adds minimal value beyond the empty schema, but baseline of 4 is appropriate for zero parameters.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose4/5

Does the description clearly state what the tool does and how it differs from similar tools?

Description clearly states 'Get items and user profiles that changed most recently', specifying verb and resource. It distinguishes from siblings like get_item and get_stories but could be more precise about what 'items' encompasses.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance on when to use this tool versus siblings like get_stories or get_user. No prerequisites or exclusions are mentioned.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

get_userA

Get a HackerNews user's public profile (karma, about, created, submissions).

Returns null if the user has no public activity or does not exist.

ParametersJSON Schema

Name	Required	Description	Default
`username`	Yes	The exact, case-sensitive HackerNews username.

Output Schema

ParametersJSON Schema

Name	Required	Description
`result`	Yes

TDQS

A4.3/5.0

Behavior4/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

Discloses that null is returned if user has no activity or doesn't exist, which is key behavioral info. No annotations provided, so description carries burden well.

Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.

Conciseness5/5

Is the description appropriately sized, front-loaded, and free of redundancy?

Two concise sentences, front-loaded with purpose, no wasted words.

Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.

Completeness5/5

Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?

Describes return fields and null behavior. Output schema exists, so return format is covered. Complete for a simple single-parameter tool.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% with username description. Description adds no additional parameter details beyond schema, so baseline 3 is appropriate.

Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.

Purpose5/5

Does the description clearly state what the tool does and how it differs from similar tools?

Clearly states it gets a HackerNews user's public profile and lists specific fields (karma, about, created, submissions). Distinguishes from sibling tools which operate on different entities.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines4/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

Implies usage context (retrieving user profile) but lacks explicit when-not-to-use or mention of alternatives. However, siblings are clearly different endpoints, so guidance is adequate.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server

RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A4.1/5.0

Disambiguation5/5

Each tool targets a distinct data type or endpoint: comments, items, max ID, stories by category, updates, and user profiles. There is no functional overlap.

Naming Consistency5/5

All tools follow the consistent 'get_' prefix with a descriptive noun (e.g., get_comments, get_stories), making the pattern predictable.

Tool Count5/5

With 6 tools, the server covers the core HackerNews API endpoints without being overly broad or sparse. Each tool is justified.

Completeness5/5

The toolset covers stories, items, comments, users, updates, and the maximum item ID. Missing operations like voting are not part of the public API, so this is complete for the domain.

Maintenance

ActivitySlowing

ResponsivenessSyncing

Resources

GitHub Repository

Need Help?

Related Servers

Unclaimed servers have limited discoverability.

Looking for Admin?

If you are the server author, to access and configure the admin panel.

Related MCP Connectors

Hacker News Mcp
io.github.varvararatta
Dive into the latest and greatest from the tech world with our Hacker News MCP server.
Developer Tools Social Media
2
hackernews A
io.github.pipeworx-io
Hacker News MCP — search and retrieve stories from Hacker News
Search Web Scraping Developer Tools
362
smithery-ai-cookbook-python-quickstart
ai.smithery
A simple MCP server built with FastMCP and python
Developer Tools
213
thoughts
ai.thoughtbox.api
An MCP server that provides read access to your cloud storage providers, bank accounts and more.
Cloud Storage Finance
2

Related MCP Servers

mcp-hn
Search Web Scraping
erithwik
A
license
A
quality
F
maintenance
A Model Context Protocol (MCP) server that provides tools for searching and fetching information from Hacker News.
Updated a year ago (2025-07-14 02:15 UTC)
4
76
MIT
Hacker News MCP Server
Search Web Scraping
GeorgeNance
A
license
D
quality
D
maintenance
An MCP server that enables AI assistants to access real-time Hacker News data including top stories, story details, comments, and search functionality.
Updated a year ago (2025-07-08 21:31 UTC)
1
25
3
MIT
@cyanheads/hn-mcp-server
Search Research & Data
cyanheads
A
license
Not graded
quality
B
maintenance
MCP server for Hacker News providing tools to fetch stories, threads, users, and search content via Firebase and Algolia APIs.
Updated 10 days ago (2026-08-25 03:01 UTC)
380
4
Apache 2.0
hn-mcp
Search Developer Tools
tomwojcik
A
license
A
quality
C
maintenance
MCP server enabling AI agents to interact with Hacker News, including fetching full comment trees with depth control, searching stories and comments, and retrieving user profiles.
Updated 6 months ago (2026-02-28 20:09 UTC)
6
5
MIT

Latest Blog Posts

Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)
By Om-Shree-0709 on July 25, 2026.
mcp
Agent Identity
OAuth 2.1
Your AI Chatbot Just Exposed Your CEO's Salary to an Intern
By Om-Shree-0709 on July 2, 2026.
Agent Identity
MCP Security
OAuth Delegation
Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)
By Om-Shree-0709 on June 30, 2026.
Agentic Ai
Prompt Injection
WebAssembly

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/Riddhimaan-Senapati/unofficial-HackerNews-MCP-CLI'

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