unofficial-HackerNews-MCP-CLI

An unofficial HackerNews MCP server and CLI. Reads the top, new, best, Ask, Show, and job story lists, individual items, threaded comments, and user profiles through one shared async client. Built with FastMCP and Typer.

Install • CLI • MCP server • Skill • Contributing

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

• hn, a Typer CLI that renders Rich tables in the terminal.
• 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.

Let your coding agent install it

You do not have to run the install commands yourself. Give this instruction to the coding agent you already use:

Run curl -fsSL https://raw.githubusercontent.com/Riddhimaan-Senapati/unofficial-HackerNews-MCP-CLI/main/skills/install-hackernews/SKILL.md and follow the instructions in its output to install the HackerNews CLI.

That command fetches the install-hackernews skill, which gives the agent each step.

If your agent supports the skills library, install the same skill with:

npx skills add Riddhimaan-Senapati/unofficial-HackerNews-MCP-CLI

Install

Requires Python 3.10+ and uv.

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

CLI

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

hn item 8863               # a single story, comment, job, or poll
hn comments 8863           # threaded comment tree (--depth, --limit, --offset)
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

hn --version               # print the installed version

Every command takes --format (-f): table (the default), json, markdown, or text. Use json for scripting; markdown and text strip HTML. For the story lists, --offset plus --limit must stay within the category's cap, 500 stories for top, new, and best, or 200 for ask, show, and job.

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

Run hn --help for the full command list, or hn <command> --help for that command's options and examples.

MCP server

Run over stdio, the default transport for MCP clients:

hn-mcp

Or over HTTP:

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

Register it with an MCP client such as Claude Desktop or Claude Code:

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

Tools

Every tool that returns items, comments, or users takes strip_html to return plain text instead of HTML.

Resources

The server also exposes read-only JSON at stable URIs: hn://stories/{category}, hn://item/{item_id}, and hn://user/{username}.

Prompts

• daily_digest(category, limit) asks the agent to summarize the day's stories.
• thread_summary(item_id, max_depth) asks the agent to summarize a comment thread.

Skill

The repo ships two Agent Skills, published on skills.sh:

• skills/hackernews/SKILL.md teaches an agent how and when to use the hn CLI and the hn-mcp MCP server.
• skills/install-hackernews/SKILL.md installs the package.

Install both with the skills CLI, or add the console scripts and let your agent load them from this directory:

npx skills add Riddhimaan-Senapati/unofficial-HackerNews-MCP-CLI

The root skills.sh.json groups the two skills on the skills.sh repo page.

Project layout

src/hn/
  client.py   # shared async HackerNews API client (httpx)
  models.py   # Pydantic models + StoryCategory (endpoint, title, cap)
  server.py   # FastMCP server (hn-mcp)
  cli.py      # Typer CLI (hn)
skills/hackernews/SKILL.md
tests/        # pytest + respx (mocked API)

How it works

client.py owns every network call and bounds concurrency. server.py and cli.py stay thin over it, so the CLI and the MCP tools behave identically. StoryCategory in models.py is the single source of truth for the six story lists: it holds a category's endpoint stem, display title, and cap. Add a category or a model field there, not in each interface.

The client keeps a short in-process cache, about 60 seconds, for item, user, and story responses. It mainly helps the long-lived MCP server; the CLI exits between commands. max_item and updates are never cached.

Changing behavior also means updating the docs in the same change: README, CONTRIBUTING, RELEASING, the agent skill, and AGENTS.md. Only the maintainer publishes a release, so follow RELEASING.md and push a tag only when asked.

Read AGENTS.md for the agent-facing rules, and CONTRIBUTING.md for the contribution workflow.

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.