# News Ycombinator Mcp

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

- **Type:** MCP server
- **Install:** `agentstack add mcp-tomwojcik-news-ycombinator-mcp`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [tomwojcik](https://agentstack.voostack.com/s/tomwojcik)
- **Installs:** 0
- **Category:** [Search](https://agentstack.voostack.com/c/search)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [tomwojcik](https://github.com/tomwojcik)
- **Source:** https://github.com/tomwojcik/news-ycombinator-mcp

## Install

```sh
agentstack add mcp-tomwojcik-news-ycombinator-mcp
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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:

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

Claude Code

```bash
claude mcp add hn -- uvx hn-mcp
```

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

Claude Desktop

Follow the MCP install [guide](https://modelcontextprotocol.io/quickstart/user), use the standard config above.

Cursor

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

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

Windsurf

Follow the Windsurf MCP [documentation](https://docs.windsurf.com/windsurf/mcp), use the standard config above.

VS Code / Copilot

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

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

From source

If you want to run from a local clone instead:

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

### Prerequisites

- Python 3.12+
- [uv](https://docs.astral.sh/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, ask_hn, show_hn), `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

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

### Run tests

```bash
make test
```

Tests use [vcrpy](https://github.com/kevin1024/vcrpy) cassettes — no network calls needed. Coverage is reported automatically.

### Re-record cassettes

If the Algolia API response format changes:

```bash
# 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](https://github.com/tomwojcik)
- **Source:** [tomwojcik/news-ycombinator-mcp](https://github.com/tomwojcik/news-ycombinator-mcp)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** no
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/mcp-tomwojcik-news-ycombinator-mcp
- Seller: https://agentstack.voostack.com/s/tomwojcik
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.