hackertube-mcp

An MCP server that answers "what should I watch for this?" with the YouTube videos Hacker News keeps telling each other to watch.

Huge props to Andrej Karpathy: this is built entirely on HackerTube, his weekend hack (announcement on X), and on his decision to release all of its data for anyone to build on. hackertube-mcp just puts it inside your agent.

▶ Watch the launch video on X (under a minute).

It runs over the open data export from HackerTube: 6,454 videos that at least three different HN commenters recommended across at least three different months, from 2007 to 2026, with LLM-written cards, 39,834 labeled HN comments, a 150-category topic tree and the "same people also recommended" graph. Ask your agent something like "I'm about to give my first conference talk, what should I watch?" and it gets back the two best picks, each with links and the reasons real HN commenters gave for watching it.

Everything runs locally. There are no API keys and no LLM calls on the server, and queries take a few milliseconds.

Unofficial. Not affiliated with HackerTube, Hacker News, Y Combinator, YouTube or Google.

Quick start

Requires uv.

git clone https://github.com/alexmartiguiu/hackertube-mcp
cd hackertube-mcp
uv run hackertube-mcp --warmup   # one-off: downloads the 18 MB export + a 70 MB embedding model
uv run hackertube-mcp -q "I need to learn how transformers work"   # try it from the terminal

Claude Code

claude mcp add hackertube -- uv --directory /path/to/hackertube-mcp run hackertube-mcp

Claude Desktop / Cursor / any MCP client

{
  "mcpServers": {
    "hackertube": {
      "command": "uv",
      "args": ["--directory", "/path/to/hackertube-mcp", "run", "hackertube-mcp"]
    }
  }
}

Related MCP server: YouTube for AI Agents

Tools

| brief_guide() | The output and figure guide (see below). Agents call it before drawing anything. |

All search tools take optional levels and content_types filters. Videos that only matter around a single news event, and videos HN only cited without recommending, are hidden by default.

Briefs: what to watch, as figures

Ask for guidance rather than a list ("I keep having outages on call, what should I watch?") and the agent builds a brief:

1. Watch this one: a single video, chosen for your situation, with why it fits and the best HN quote.

2. Figure 1, the video in one picture: the video's core idea drawn as a paper-style figure, with inputs, the mechanism in a dashed container, and what you'll get.

3. Figure 2, your problem across all sources: up to three concept columns (what goes wrong, then what to do), each with a small thumbnail of the video that explains that piece.

Example: examples/brief_5min_talk.html (rendered) is what a fresh agent produced for "I have a 5-minute presentation in two weeks. Make me a brief." It was given nothing but this MCP. It found the guide through the server instructions and picked Patrick Winston's How to Speak as the one to watch. Figure 1 shows the lecture as one talk's timeline, and Figure 2 shows what goes wrong in a short talk and what counters it. One CSS line was fixed by hand, so the chip captions stack.

The format lives in brief_guide.md and reaches agents three ways:

• the server instructions point agents to it

• the brief_guide tool returns it

• it's exposed as the resource hackertube://brief-guide and the prompt brief(situation) (/mcp__hackertube__brief in Claude Code)

It covers the figure grammar, the palette (light and dark), the layouts for each question type, and grounding rules (every claim about a video must trace back to a card summary or HN comment, general background is flagged as such, and the agent may not invent a video's mechanism). Agents are expected to adapt it to their client. Fork the file to change the house style.

How ranking works

1. The query is embedded with BAAI/bge-small-en-v1.5, the model HackerTube used for embeddings.npy. recommend also embeds each also_phrased rephrasing. A video scores the average of its best and its mean similarity across the phrasings, so one stray phrasing can't pull in off-topic hits.

2. Cosine similarity is mapped to a relevance score in [0, 1].

3. That relevance is scaled by HackerTube's quality score: the number of distinct months HN recommended the video, log-squashed, with weight 0.3. Quality reorders relevant videos, but it can't push an off-topic classic to the top.

4. Re-uploads are removed by deduplicating on normalized title.

A cross-encoder reranker (jinaai/jina-reranker-v1-turbo-en) is available with HACKERTUBE_RERANK=1. It's off by default. In testing it was better on exact titles but scored situation-style questions ("I'm becoming an engineering manager") close to zero, and it adds a 130 MB model and about 600 ms per query.

scripts/try_queries.py runs 24 sample questions so you can eyeball the results.

What it's good at: technical topics HN loves, such as distributed systems, performance, compilers, cryptography, ML, computing history and math intuition.

What's thin: career and soft skills (salary negotiation, management), and anything HN doesn't link to much. Situation-style questions work much better when the agent passes topical rephrasings in also_phrased, and the tool description tells it to.

Configuration

Tests

uv run python tests/test_stdio.py     # launches the server over stdio and calls every tool
uv run python scripts/try_queries.py  # eyeball ranking quality

Acknowledgements

This project stands entirely on HackerTube, the weekend hack by Andrej Karpathy (announcement on X). He had Claude Opus 5.5 filter 43M comments from 20 years of Hacker News down to the 6,454 videos people keep recommending, then released the cards, labeled comments, topic tree and embeddings for anyone to build on. All of the curation, the video cards and the vectors this server searches come from that work. Thank you to Andrej, to the Claude-built HackerTube pipeline, and to the HN commenters who have been pointing each other at great talks for two decades.

License and credits

Code: MIT.

The data isn't included in this repo. It's downloaded at runtime from hackertube.org/data under ODC-By 1.0. Credit goes to HackerTube (https://hackertube.org) and the open-index/hacker-news dataset. HN comments remain the work of their authors. Video titles and channel names belong to their creators. The summaries and labels were written by an LLM, so expect a few to be off.