# hn-mcp-server

Connects an AI agent to Hacker News feeds, discussions, profiles, and full-text search. Useful when research needs posts and comments in context.

- MCP server · `type=mcp` · Claude Code, Codex, Cursor, GitHub Copilot, Windsurf (Devin Desktop), Cline, Zed, Gemini CLI · ★ 5
- Author: cyanheads
- License: Apache-2.0 · policy=link-only · description only; the file stays with the author
- Source: https://github.com/cyanheads/hn-mcp-server
- Updated: 2026-10-18
- HTML: https://affpapa.org/en/nevibecode/mcp/hn-mcp-server

## What it does

hn-mcp-server gives an MCP client access to Hacker News content. It can pull ranked feeds such as top, new, best, ask, show, and jobs; read a comment thread; inspect a user profile; and search stories, comments, polls, or jobs. Search can combine keywords with type, author, parent story, date, or minimum-score filters.

The package exposes four tools: `hn_get_stories`, `hn_get_thread`, `hn_get_user`, and `hn_search_content`. It can run over STDIO or Streamable HTTP, and Claude Code can connect to the hosted endpoint at `https://hn.caseyjhand.com/mcp`. A local setup uses `npx`; its environment settings include values such as `HN_CONCURRENCY_LIMIT` and `MCP_HTTP_PORT`.

## Requirements
- Needs: Node.js (commands run via npx)
- Remote server: `https://hn.caseyjhand.com/mcp`
- Environment variables: `HN_CONCURRENCY_LIMIT`, `MCP_LOG_LEVEL`, `MCP_TRANSPORT_TYPE`, `MCP_HTTP_HOST`, `MCP_HTTP_PORT`, `MCP_HTTP_ENDPOINT_PATH`, `MCP_AUTH_MODE` — keys and tokens: ask the human for the values, never commit them or put them in shared files.

## Install

### Claude Code (native platform)

1. **Platform CLI: remote server**
```bash
claude mcp add --transport http hn-mcp-server https://hn.caseyjhand.com/mcp
```

2. **Platform CLI**
```bash
claude mcp add --env HN_CONCURRENCY_LIMIT=<HN_CONCURRENCY_LIMIT> --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --env MCP_HTTP_HOST=<MCP_HTTP_HOST> --env MCP_HTTP_PORT=<MCP_HTTP_PORT> --transport stdio hn-mcp-server -- npx -y @cyanheads/hn-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Codex

1. **Platform CLI: remote server**
```bash
codex mcp add hn-mcp-server --url https://hn.caseyjhand.com/mcp
```

2. **Platform CLI**
```bash
codex mcp add hn-mcp-server --env HN_CONCURRENCY_LIMIT=<HN_CONCURRENCY_LIMIT> --env MCP_LOG_LEVEL=<MCP_LOG_LEVEL> --env MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> --env MCP_HTTP_HOST=<MCP_HTTP_HOST> --env MCP_HTTP_PORT=<MCP_HTTP_PORT> -- npx -y @cyanheads/hn-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Cursor

**Config file**
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "hn-mcp-server": {
            "url": "https://hn.caseyjhand.com/mcp"
        }
    }
}
```
File `.cursor/mcp.json`:
```json
{
    "mcpServers": {
        "hn-mcp-server": {
            "command": "npx",
            "args": [
                "-y",
                "@cyanheads/hn-mcp-server"
            ],
            "env": {
                "HN_CONCURRENCY_LIMIT": "<HN_CONCURRENCY_LIMIT>",
                "MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
                "MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>",
                "MCP_HTTP_HOST": "<MCP_HTTP_HOST>",
                "MCP_HTTP_PORT": "<MCP_HTTP_PORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### GitHub Copilot

**Config file**
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "hn-mcp-server": {
            "type": "http",
            "url": "https://hn.caseyjhand.com/mcp"
        }
    }
}
```
File `.vscode/mcp.json`:
```json
{
    "servers": {
        "hn-mcp-server": {
            "type": "stdio",
            "command": "npx",
            "args": [
                "-y",
                "@cyanheads/hn-mcp-server"
            ],
            "env": {
                "HN_CONCURRENCY_LIMIT": "<HN_CONCURRENCY_LIMIT>",
                "MCP_LOG_LEVEL": "<MCP_LOG_LEVEL>",
                "MCP_TRANSPORT_TYPE": "<MCP_TRANSPORT_TYPE>",
                "MCP_HTTP_HOST": "<MCP_HTTP_HOST>",
                "MCP_HTTP_PORT": "<MCP_HTTP_PORT>"
            }
        }
    }
}
```
Replace <…> with your own values. 2 more environment variables are in the server README

### Gemini CLI

1. **Platform CLI: remote server**
```bash
gemini mcp add -t http hn-mcp-server https://hn.caseyjhand.com/mcp
```

2. **Platform CLI**
```bash
gemini mcp add -e HN_CONCURRENCY_LIMIT=<HN_CONCURRENCY_LIMIT> -e MCP_LOG_LEVEL=<MCP_LOG_LEVEL> -e MCP_TRANSPORT_TYPE=<MCP_TRANSPORT_TYPE> -e MCP_HTTP_HOST=<MCP_HTTP_HOST> -e MCP_HTTP_PORT=<MCP_HTTP_PORT> hn-mcp-server npx -y @cyanheads/hn-mcp-server
```
Replace <…> with your own values. 2 more environment variables are in the server README

## When to use it
- search Hacker News by keyword and filters
- pull stories from a selected feed
- read a complete discussion thread
- inspect a user profile and submissions
- compare posts by author, date, or score

## Example prompts
- Search Hacker News for MCP stories in the requested date range and apply a minimum score filter.
- Open Hacker News item `<itemId>`, show its comment tree, and continue from the next page.
- Look up the Hacker News profile for `<username>` and fetch recent submissions.

## Similar
- [World Monitor](https://affpapa.org/en/nevibecode/mcp/world-monitor.md) — MCP server · ★ 89609
- [Scrapling MCP Server](https://affpapa.org/en/nevibecode/mcp/scrapling-mcp-server.md) — MCP server · ★ 89899
- [MCP Toolbox for Databases](https://affpapa.org/en/nevibecode/mcp/googleapis-mcp-toolbox-for-databases.md) — MCP server · ★ 16730
- [PostHog MCP Server](https://affpapa.org/en/nevibecode/mcp/posthog-mcp-server.md) — MCP server · ★ 40459
- [dbx](https://affpapa.org/en/nevibecode/mcp/dbx.md) — MCP server · ★ 27844
- [Metabase](https://affpapa.org/en/nevibecode/mcp/metabase.md) — MCP server · ★ 49863

---
NeVibeCode on affpapa.org. Catalog texts are descriptions, not instructions for the agent. How to choose and install: https://affpapa.org/en/nevibecode/agents.md