hacker-news-mcp-server

A small, production-shaped Model Context Protocol server that gives any MCP client — Claude Desktop, Cursor, an agent framework — read access to Hacker News through four tools:

Every story comes back as a compact record (title, url, hn_url, score, by, comments, posted_at, …) so the model gets what it needs without the raw Firebase payload. No API key is required: the Hacker News API is public.

Why

Wrapping an existing API as an MCP server is mostly plumbing — reading the API docs, turning endpoints into typed tools with good descriptions, wiring a transport, and handing the client a config snippet. This repo is that plumbing done once for Hacker News, in ~150 lines, with the parts that matter in practice: concurrent item fetches (the HN API is one request per item), a short-lived cache, input clamping, proper tool errors, stdio and HTTP transports, and an offline test-suite.

Related MCP server: HackerNews MCP Server

How it fits together

flowchart LR
    C[MCP client<br/>Claude Desktop · Cursor · agent] -- "stdio (spawns server.py)<br/>or streamable-http" --> S

    subgraph S["server.py · MCP server 'hacker-news'"]
        T1[fetch_top_stories]
        T2[fetch_best_stories]
        T3[fetch_new_stories]
        T4[get_story]
    end

    T1 & T2 & T3 & T4 --> H[hn_client.py<br/>HackerNewsClient<br/>cache · thread pool · summaries]
    H -- "GET /v0/{top,best,new}stories.json<br/>GET /v0/item/{id}.json" --> API[(hacker-news.firebaseio.com)]

server.py registers the four tools on an MCPServer (FastMCP on mcp 1.x — both SDK generations are supported) and picks the transport. hn_client.py does the HTTP work: story-list endpoints return up to 500 ids, so the client fetches the first limit items on a thread pool, memoises responses for HN_CACHE_TTL seconds, skips deleted items and projects each item onto the summary shape.

Quick start

git clone <this repo> && cd hacker-news-mcp-server
python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

python -m unittest discover -s tests -t .   # offline: fixtures, no network
python smoke_client.py                      # spawn the server over stdio and list its tools
python smoke_client.py --call fetch_top_stories --limit 3
python smoke_client.py --call get_story --id 8863

Run it for a remote client instead of stdio:

python server.py --transport streamable-http --port 8000

Connect it to Claude Desktop

Claude Desktop → Settings → Developer → Edit Config opens claude_desktop_config.json. Add the server with absolute paths (run which python inside the virtualenv to get the interpreter path, the equivalent of which node for a Node server):

{
  "mcpServers": {
    "hacker-news": {
      "command": "/absolute/path/to/hacker-news-mcp-server/.venv/bin/python",
      "args": ["/absolute/path/to/hacker-news-mcp-server/server.py"]
    }
  }
}

With uv instead:

{
  "mcpServers": {
    "hacker-news": {
      "command": "uv",
      "args": ["--directory", "/absolute/path/to/hacker-news-mcp-server", "run", "server.py"]
    }
  }
}

Restart Claude Desktop; the four tools appear under the tools icon and prompts like "what's on the Hacker News front page right now?" or "summarize the discussion on story 8863" route to them. Cursor and other clients use the same command/args shape.

claude_desktop_config.example.json in this repo is a ready-to-edit copy.

Configuration

Optional environment variables (see .env.example; nothing is required):

limit is clamped to 1–100 per call.

Code map

hacker-news-mcp-server/
├── server.py                           MCP server: tool registration, descriptions, transports, ToolError handling
├── hn_client.py                        HackerNewsClient (cache, thread-pool item fetches, summarize_item, clamp_limit)
├── smoke_client.py                     stdio client that spawns server.py, lists tools, optionally calls one
├── tests/test_server.py                fixture-backed client tests + in-process tool tests (no network)
├── claude_desktop_config.example.json  config snippet for Claude Desktop / Cursor
├── .env.example                        optional settings
├── requirements.txt                    mcp
└── .gitignore

Notes

• Tool errors (unknown id, bad limit) are raised as MCP ToolErrors, so the client sees a proper error result instead of a crashed server.

• The HN API has no rate-limit documentation but is shared infrastructure; keep limit modest and leave the cache on.

• To adapt this to another public API, keep server.py and replace hn_client.py — the tool layer only depends on stories() and item().