<!--
SPDX-FileCopyrightText: 2026 Peter Lemenkov <lemenkov@gmail.com>
SPDX-License-Identifier: Apache-2.0
-->

# mcp-hackernews

MCP server for [Hacker News](https://news.ycombinator.com) — search, read, and watch topics for what is new since you last looked.

## Tools

| Tool | Description |
|------|-------------|
| `hn_search` | Search Hacker News (Algolia) with tag/points/date filters |
| `hn_get_item` | Get a single item (story, comment, poll, or job) |
| `hn_get_thread` | Expand a story's comment tree |
| `hn_get_stories` | List a curated feed (top/new/best/ask/show/job) |
| `hn_get_user` | Get a user's profile |
| `hn_list_watches` | List saved topic watches |
| `hn_check_new` | Items matching a watch since its watermark (read-only) |
| `hn_watch_topic` | Create or update a topic watch |
| `hn_mark_seen` | Advance a watch's watermark |
| `hn_delete_watch` | Delete a watch |

## Install

```bash
python3 -m venv venv
venv/bin/pip install -e .
venv/bin/pip install -e ".[systemd]"  # optional: journald logging
```

## Configuration

```bash
HOST=127.0.0.1
PORT=8800
HN_MCP_DB=/var/lib/mcp-hackernews/watches.db  # watch store
```

## License

Apache-2.0