Necl Hn MCP

What adjacentai/necl-hn-mcp MCP server does

The adjacentai/necl-hn-mcp MCP server gives an MCP client access to selected Hacker News data sources. It supports ranked stories from a configurable time window, standard Hacker News feeds, individual story details, top-level comment threads, and full-text search across posts and comments.

The server is intended for agents that need current Hacker News context without manually handling the underlying APIs. Typical workflows include finding recent stories, inspecting a story's metadata, reading its discussion, and searching for related topics. Results are returned as structured data suitable for follow-up tool calls and summaries.

How it works

The adjacentai/necl-hn-mcp MCP server uses the public Hacker News API for story, feed, and comment data. Full-text queries use the Algolia Hacker News API. Neither service requires an API key for the documented setup.

The top-story tool accepts a result limit and a time period in hours, then ranks matching stories by score. Category queries can target top, new, best, ask, show, or job. Search accepts a query and a sort option, including date-based sorting for recent activity.

Comment retrieval is limited to top-level comments. Each returned comment includes a replies_count field that can indicate whether deeper replies exist, but nested replies are not recursively loaded.

Setup and configuration

The documented recommended setup runs the project with uvx directly from its GitHub repository. The repository requires Python 3.10 or newer, and uv can be installed with pip or Homebrew if it is not already available. A pip-based setup is also documented: install the repository and start it with python -m necl_hn_mcp.

A Claude Desktop or other MCP client configuration needs the server command and arguments. No environment variables, account registration, or credential values are required. After changing an MCP configuration, fully restart the client so the tools are discovered.

For development, the project can be cloned and installed in editable mode with its development dependencies. The README also documents running the source server with MCP Inspector.

Tools and capabilities

The adjacentai/necl-hn-mcp MCP server provides these tools:

• hn_top_stories(limit, hours) returns highly ranked stories from the requested recent time range. Its documented default is 10 stories from the previous 24 hours.
• hn_get_story(id) retrieves metadata such as the title, URL, score, author, comment count, and posting time.
• hn_get_comments(id, limit) returns a ranked list of top-level comments for a story.
• hn_search(query, sort) searches Hacker News posts and comments through Algolia.
• hn_category(category, limit) reads one of the supported category feeds: top, new, best, ask, show, or job.

These capabilities can support daily content briefs, keyword-based research, monitoring of new or best stories, newsletter preparation, and searches across Ask HN discussions.

Limitations and notes

Hacker News Firebase requests can take longer when a query scans a large range or requests many items. The README gives a 10-second per-request default timeout and recommends using a smaller limit for long time windows.

Algolia may index new Hacker News content with a delay of roughly five to fifteen minutes. Recent searches may therefore return incomplete results; sorting by date is suggested when looking for fresh activity. Comment results intentionally omit recursive replies, so they should not be treated as a complete discussion tree.

The project is released under the MIT license. Its documented integrations are the public Hacker News API and Algolia's Hacker News search API; no paid API service is required.