necl-hn-mcp

Hacker News tools for AI agents. Top stories, story details, comments thread, full-text search.

Zero credentials. Public HN API. Install and use.

Built by NeCL — AI engineering studio. Production-tested: this is the exact HN layer that powers our internal content agent, running 3× daily for months.

Tools

Why this MCP

• Zero credentials, zero config — public HN API, no rate limits worth worrying about, no signup.
• Battle-tested code — extracted from our internal HN-to-drafts content engine that's been running 3×/day for months.
• Built for AI agents — every tool returns clean structured data that LLMs can chain together (search → top story → comments → summary).
• Use case — content research, trend monitoring, automatic news digests, prompt-context enrichment.

Install

Via uvx (recommended — no setup)

uvx runs the package in an ephemeral env. No pip install, no venv. Add to your mcp.json (Claude Desktop, Claude Code, or any MCP client):

{
  "mcpServers": {
    "necl-hn": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/adjacentai/necl-hn-mcp.git",
        "necl-hn-mcp"
      ]
    }
  }
}

Don't have uvx? Install it: pip install uv or brew install uv.

Via pip + python -m

pip install git+https://github.com/adjacentai/necl-hn-mcp.git

Then in mcp.json:

{
  "mcpServers": {
    "necl-hn": {
      "command": "python",
      "args": ["-m", "necl_hn_mcp"]
    }
  }
}

From source (for development)

git clone https://github.com/adjacentai/necl-hn-mcp.git
cd necl-hn-mcp
pip install -e ".[dev]"

Then use the same python -m necl_hn_mcp config as above.

Example use in Claude

Once installed, just ask Claude things like:

• "What are the top 5 stories on HN in the last 6 hours?"
• "Get the comments thread for HN story 38420000"
• "Search HN for posts about RAG performance, sorted by date"
• "Show me everything in the Ask HN category right now"
• "Find the top 3 Show HN posts about AI agents this week"

Claude will call the right tool, no further setup.

What you can build with this

• Daily content brief — pull top HN stories, summarize, generate cross-platform posts.
• Competitive research bot — search HN for mentions of your competitors, surface negative comments.
• Trend detector — monitor new and best categories on a cron, alert when a topic spikes.
• Newsletter pipeline — search by keyword window, cluster results, generate editorial digest.
• Customer-discovery agent — search Ask HN for problems your product solves, generate cold-outreach drafts.
• Tech-radar updater — periodically scan show category for new tools in your stack.

Troubleshooting

"mcp command not found" / install errors. Make sure your Python is 3.10+. If using uvx, ensure uv is installed (pip install uv). For pip install: pip install necl-hn-mcp then verify python -m necl_hn_mcp --help doesn't error.

Tool calls timeout. HN's Firebase API can be slow when fetching many items (e.g. hn_top_stories(limit=30, hours=168) scans 200 stories). Default timeout is 10s per request. For long-window queries, use lower limit.

Algolia returns no hits. Algolia indexes HN content with a delay (~5-15 min for fresh items). Try sort="date" for recent activity.

Comments thread is empty for a story I see on HN. hn_get_comments returns only top-level comments. Replies aren't recursively fetched (to keep token cost predictable for LLMs). Use the replies_count field on each comment to know if there's deeper discussion.

Tools don't show up in Claude. After editing mcp.json, fully restart Claude Desktop / Claude Code (not just reload). Check the MCP logs in Settings → Developer.

Pair with

• necl-content-poster Skill — turn HN stories into ready-to-publish posts for TG/LinkedIn/Threads.

Full pipeline:

necl-hn-mcp (find story) → necl-content-poster (write 3 posts) → you publish

Built by NeCL

neclco.com — production AI engineering. RAG systems, voice agents, Telegram bots, custom MCPs and content engines for companies that need more than wrappers.

Need a custom MCP wired to your internal APIs / databases / SaaS? Visit neclco.com.

Development

git clone https://github.com/adjacentai/necl-hn-mcp.git
cd necl-hn-mcp
pip install -e ".[dev]"

# Run locally with MCP inspector
mcp dev src/necl_hn_mcp/server.py

License

MIT — see LICENSE.

Follow NeCL: Telegram · LinkedIn · X · Site