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.

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 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)
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

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

hn stories top -n 5 --json | jq -r '.[] | "\(.title) (\(.url // .hn_url))"'
hn user pg --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

Skill

skills/hackernews/SKILL.md is an Agent Skill that teaches an agent how and when to use the hn CLI and the hn-mcp MCP server. It is published on skills.sh. Install it with the skills CLI, or add the console scripts and let your agent load it from this directory:

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

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.