Plinth HN MCP

A small, production-clean Model Context Protocol server that gives any MCP client (Claude Desktop, Claude Code, Cursor, ...) live Hacker News data — top/new/best story feeds, individual items, and public user profiles — straight from the free, no-API-key Hacker News Firebase API.

It's free and MIT-licensed. The point isn't just "Hacker News in your LLM" — it's a reference for what an MCP server should look like when you actually have to run it: rate-limited, retried, observable, and validated.

Why this one

Most example MCP servers are toys that fall over the first time an LLM calls a tool in a loop or the upstream hiccups. This one ships the boring stuff that keeps a server alive in production:

• Outbound rate limiting — a token bucket caps how fast we hit the upstream, which matters here because the story feeds fan out into many per-item fetches, so an over-eager agent can't get you throttled.
• Exponential backoff with full jitter — transient 429/5xx/network errors are retried with capped, jittered delays that honor Retry-After.
• Structured JSON logging to stderr — one JSON object per line, ready for a log shipper. Never writes to stdout (that's the JSON-RPC channel — polluting it corrupts the session).
• Graceful shutdown — SIGTERM/SIGINT close the HTTP client cleanly.
• Input validation on every tool argument — bad ids, empty usernames, or out-of-range limits fail fast with a clear, model-recoverable error instead of a stack trace.
• A real health check tool — reports version and live upstream reachability.
• Optional API-key gate — off by default (the upstream is public); flip on with one env var if you expose this server to others.

Quickstart (one command)

With uv installed, no clone or install needed:

uvx plinth-hn-mcp

Or with pip:

pip install plinth-hn-mcp
plinth-hn-mcp

The server speaks MCP over stdio. It's meant to be launched by an MCP client, not run interactively — but the command above will start and block, logging a startup line to stderr, which confirms it's healthy.

Use with Claude Desktop / Claude Code

Add this to your MCP client config (for Claude Desktop: claude_desktop_config.json; for Claude Code: claude mcp add or your project's .mcp.json):

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

Then ask: "What are the top 5 stories on Hacker News right now, and who posted the top one?"

Tools

Tool	What it does
top_stories(limit=10)	Current front-page (top) stories.
new_stories(limit=10)	Newest submitted stories.
best_stories(limit=10)	Highest-scoring stories.
get_item(id)	A single story/comment/job/poll by id.
get_user(username)	Public user profile (karma, created, about).
health_check()	Server version + live upstream reachability.

Story summaries include id, title, url, score, by, comment count, and an hn_url permalink. Every data tool returns a JSON object with ok: true and the payload, or ok: false with error and message on failure.

Configuration

All optional. Defaults are tuned for the free public upstream.

Env var	Default	Purpose
PLINTH_API_KEY	(unset)	If set, every data tool requires a matching api_key arg.
PLINTH_LOG_LEVEL	INFO	DEBUG / INFO / WARNING / ERROR.
PLINTH_MAX_LIST_LIMIT	50	Max items a single list tool will hydrate.
PLINTH_RATE_LIMIT_REQUESTS	10	Max upstream requests per window.
PLINTH_RATE_LIMIT_WINDOW_SECONDS	1.0	Rate-limit window length.
PLINTH_MAX_RETRIES	4	Retries on transient upstream failures.
PLINTH_BACKOFF_BASE_SECONDS	0.5	Base for exponential backoff.
PLINTH_BACKOFF_MAX_SECONDS	20.0	Backoff cap.
PLINTH_REQUEST_TIMEOUT_SECONDS	15.0	Per-request timeout.

Development

python -m venv .venv && source .venv/bin/activate
pip install -e ".[dev]"
pytest

Tests mock the network (via respx), so they pass fully offline.

---

Want the whole toolkit?

This repo is one polished example. If you're building MCP servers for real and want to skip the yak-shaving:

→ MCP Server Starter Kit

Want Python and TypeScript templates, more worked examples, Dockerfiles, and a deploy + directory-publishing guide? (how to actually get your server listed in the MCP registries). Same SRE hygiene as this repo, batteries included.

More from the brand at plinthkit.vercel.app.

License

MIT © Plinth. Data from the Hacker News API (public, no auth).