News Ycombinator Mcp

hn-mcp

[](https://pypi.org/project/hn-mcp/) [](https://www.python.org/downloads/) [](https://codecov.io/gh/tomwojcik/news-ycombinator-mcp) [](LICENSE)

HN threads have 500+ comments nested 10 levels deep. Your AI agent needs to read them without blowing its context window.

hn-mcp is an MCP server that gives AI agents full access to Hacker News — complete comment trees, search, and user profiles — with depth control so they can explore progressively instead of fetching everything at once.

Features

• Full comment trees — no depth limits, no truncation
• Depth control — fetch just top-level comments or the entire tree
• Smart pruning — reply_count at cut-off points so agents decide what to expand
• Search — full-text search across stories and comments with filters
• No API keys — uses the public Algolia HN API
• 100% test coverage — tested with VCR cassettes, no network calls needed

Typical agent workflow

1. get_thread(42123456, depth=1)       → story + 85 top-level comments with reply_counts
2. Agent picks Comment A (47 replies)
3. get_comment_tree(comment_a_id)      → full 47-reply subtree
4. Agent summarizes branch, picks next

Or for smaller threads, just get_thread(id, depth=-1) to get the entire tree at once.

Getting started

Standard config works in most tools:

{
  "mcpServers": {
    "hn": {
      "command": "uvx",
      "args": ["hn-mcp"]
    }
  }
}

Claude Code

claude mcp add hn -- uvx hn-mcp

Add --scope user to make it available in all projects.

Claude Desktop

Follow the MCP install guide, use the standard config above.

Cursor

Add to your Cursor MCP config (~/.cursor/mcp.json):

{
  "mcpServers": {
    "hn": {
      "command": "uvx",
      "args": ["hn-mcp"]
    }
  }
}

Windsurf

Follow the Windsurf MCP documentation, use the standard config above.

VS Code / Copilot

Add to your VS Code MCP config (.vscode/mcp.json):

{
  "mcpServers": {
    "hn": {
      "command": "uvx",
      "args": ["hn-mcp"]
    }
  }
}

From source

If you want to run from a local clone instead:

claude mcp add hn -- uv run --directory /absolute/path/to/news-ycombinator-mcp hn-mcp

Prerequisites

• Python 3.12+
• uv (provides uvx)

Tools

| Tool | Description | Key Inputs | Returns | |---|---|---|---| | get_thread | Fetch a story and its comment tree | story_id, depth (0=story only, 1=top-level, N=N levels, -1=full tree) | Story metadata + pruned comment tree | | get_comment_tree | Dive into a specific comment's reply subtree | comment_id, depth (default: -1, full subtree) | Comment + nested replies | | get_stories | Browse HN by category | category (top, new, askhn, showhn), count | List of story summaries | | search_stories | Full-text search for stories | query, sort_by (relevance/date), count, page | Paginated story results | | search_comments | Full-text search for comments | query, sort_by, story_id, author, count, page | Paginated comment results | | get_user | Fetch a user profile | username | Username, karma, about, created date |

Depth parameter

The depth parameter on get_thread and get_comment_tree controls how much of the tree you get:

depth=0   (no comments — story metadata only)
depth=1   Comment A (reply_count=3)       ← just the comment + count
depth=2   Comment A                        ← comment + direct replies
            ├── Reply A1 (reply_count=2)
            ├── Reply A2 (reply_count=0)
            └── Reply A3 (reply_count=1)
depth=-1  Full tree, no pruning

Development

git clone https://github.com/tomwojcik/news-ycombinator-mcp
cd news-ycombinator-mcp
make venv
make install

Run tests

make test

Tests use vcrpy cassettes — no network calls needed. Coverage is reported automatically.

Re-record cassettes

If the Algolia API response format changes:

# In tests/conftest.py, temporarily change record_mode to "new_episodes"
uv run pytest
# Then change it back to "none"

Project structure

src/hn_mcp/
├── app.py               # FastMCP instance + tree pruning helpers
├── client.py            # HNClient — async Algolia API client
├── server.py            # Entrypoint
├── types.py             # TypedDict definitions for all responses
└── tools/
    ├── get_thread.py
    ├── get_comment_tree.py
    ├── get_stories.py
    ├── search_stories.py
    ├── search_comments.py
    └── get_user.py

License

MIT — see [LICENSE](LICENSE).

Contributing

Contributions welcome. Please open an issue first to discuss what you'd like to change.

When submitting a PR:

1. Add tests for new functionality
2. Record VCR cassettes for any new API calls
3. Ensure uv run pytest passes with 100% coverage

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: tomwojcik
• Source: tomwojcik/news-ycombinator-mcp
• License: MIT

Install and usage instructions live in the source repository linked above.