# hackernews-mcp-server

A [Model Context Protocol](https://modelcontextprotocol.io) server that lets AI assistants read [Hacker News](https://news.ycombinator.com).

Plug it into Cursor, Claude Desktop or Claude Code and ask things like:

- "What is on the front page of Hacker News right now?"
- "Summarize the top 5 Show HN posts."
- "Are there any Ask HN threads about Rust today?"

It uses the official [Hacker News API](https://github.com/HackerNews/API). No API key or account is needed.

## Tool

### `fetch_hacker_news`

Fetches current stories with title, link, score, author and comment count.

| Parameter  | Type    | Default | Description                                          |
| ---------- | ------- | ------- | ---------------------------------------------------- |
| `category` | string  | `top`   | `top`, `new`, `best`, `ask`, `show` or `job`         |
| `limit`    | integer | `10`    | Number of stories, from 1 to 30                      |

The result comes in two forms: a compact text list for the model to read, and structured content for clients that support it.

```json
{
  "category": "top",
  "stories": [
    {
      "id": 12345678,
      "title": "Show HN: An example project",
      "url": "https://example.com/project",
      "discussionUrl": "https://news.ycombinator.com/item?id=12345678",
      "score": 347,
      "author": "someuser",
      "comments": 72,
      "postedAt": "2026-01-15T12:00:00.000Z"
    }
  ]
}
```

Ask HN and similar posts also carry a `text` field with the body in plain text, truncated to 500 characters.

## Setup guide

### 1. Build the server

Requires Node.js 18 or newer.

```bash
git clone https://github.com/wallaceluis/hackernews-mcp-server.git
cd hackernews-mcp-server
npm install
npm run build
```

Take note of the **absolute path** to `dist/index.js`; every client below needs it. Examples:

- macOS / Linux: `/Users/you/hackernews-mcp-server/dist/index.js`
- Windows: `C:\\Users\\you\\hackernews-mcp-server\\dist\\index.js` (backslashes doubled inside JSON)

### 2. Connect your client

#### Cursor

Create `.cursor/mcp.json` in your project (or `~/.cursor/mcp.json` to enable it everywhere):

```json
{
  "mcpServers": {
    "hackernews": {
      "command": "node",
      "args": ["/absolute/path/to/hackernews-mcp-server/dist/index.js"]
    }
  }
}
```

Then open **Cursor Settings > MCP** and check that `hackernews` is listed and enabled. The tool is available to the agent in chat.

#### Claude Desktop

Open **Settings > Developer > Edit Config**, which opens `claude_desktop_config.json`:

- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`

Add the server:

```json
{
  "mcpServers": {
    "hackernews": {
      "command": "node",
      "args": ["/absolute/path/to/hackernews-mcp-server/dist/index.js"]
    }
  }
}
```

Quit and reopen Claude Desktop. The `fetch_hacker_news` tool shows up in the tools menu of the chat input.

#### Claude Code

```bash
claude mcp add hackernews -- node /absolute/path/to/hackernews-mcp-server/dist/index.js
```

Run `/mcp` inside Claude Code to confirm the server is connected.

### 3. Try it

Ask your assistant: *"Use Hacker News to tell me what developers are talking about today."*

## Troubleshooting

| Problem                                   | Fix                                                                                          |
| ----------------------------------------- | -------------------------------------------------------------------------------------------- |
| Server does not show up or fails to start | Check that the path is absolute and that `dist/index.js` exists (run `npm run build`)        |
| `node` not found                          | The client may not share your shell's `PATH`. Use the full path to `node` as `command`       |
| "The Hacker News API is unreachable"      | The machine needs outbound HTTPS access to `hacker-news.firebaseio.com`                      |
| Changes to the code have no effect        | Rebuild with `npm run build` and restart the client                                          |

To test the server on its own, use the MCP Inspector:

```bash
npm run inspect
```

## Development

```bash
npm run dev        # compile in watch mode
npm run typecheck
npm run inspect    # open the MCP Inspector against the built server
```

| File                | Responsibility                                               |
| ------------------- | ------------------------------------------------------------ |
| `src/index.ts`      | Entrypoint: connects the server to the stdio transport       |
| `src/server.ts`     | MCP server and the `fetch_hacker_news` tool definition       |
| `src/hackernews.ts` | Hacker News API client and result formatting                 |

The server talks to the client over stdio, so `stdout` is reserved for the protocol. Log with `console.error`, never `console.log`.

### How it works

The Hacker News API exposes a ranked list of ids per category and one endpoint per item. The server reads the list, loads the first `limit` items in parallel (10 second timeout each), drops deleted and dead posts, and converts HTML bodies to plain text. A story that fails to load is skipped instead of failing the whole call. Errors are returned as tool errors so the model can see what went wrong.

## License

[MIT](LICENSE)