hacker-news-mcp-py 0.2.0

MCP server for searching Hacker News stories via Algolia

Hacker News MCP

MCP server for searching Hacker News stories through the Algolia Hacker News Search API.

The server is read-only and is designed to run through uvx.

The PyPI distribution name is mcp-hacker-news (the name hacker-news-mcp is rejected as too similar to existing projects).

Install and Run

Install from PyPI with pip:

pip install mcp-hacker-news
hacker-news-mcp

(mcp-hacker-news is also installed as a command.)

Or run with uv:

uvx mcp-hacker-news

During local development:

uv run hacker-news-mcp

MCP Configuration

{
  "mcpServers": {
    "hacker-news": {
      "command": "uvx",
      "args": ["mcp-hacker-news"]
    }
  }
}

Running from a Local Source Copy

If you want to run a local copy of this repository instead of resolving the package through uvx, clone the source code and install dependencies:

git clone https://github.com/m-higuchi/hacker-news-mcp
cd hacker-news-mcp
uv sync

Then use the following MCP configuration:

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

Replace /path/to/hacker-news-mcp with the absolute path to the directory where you cloned this repository (the folder that contains pyproject.toml).

Backend API

This server uses Algolia's Hacker News Search API as the primary backend:

https://hn.algolia.com/api/v1

Story searches always include tags=story. Date range searches call /search_by_date and convert ISO dates into Algolia created_at_i numeric filters.

Tools

search_stories_by_date

Search stories within a date range.

Input:

{
  "query": "AI",
  "start_date": "2026-04-01",
  "end_date": "2026-04-27",
  "limit": 20,
  "page": 0
}

Behavior:

• start_date and end_date accept YYYY-MM-DD or ISO datetime strings.
• Date-only start_date is interpreted as 00:00:00Z.
• Date-only end_date is interpreted as 23:59:59Z.
• limit defaults to 20 and is capped at 100.
• page is zero-based.

search_stories

Search stories by relevance or date.

Input:

{
  "query": "AI",
  "sort": "relevance",
  "limit": 20,
  "page": 0
}

sort can be relevance or date.

get_story

Fetch a story by Hacker News item ID.

Input:

{
  "story_id": 123456
}

get_user

Fetch a Hacker News user profile by username.

Input:

{
  "username": "pg"
}

Example Prompts

Once the MCP server is connected, you can ask the AI questions like the following.

Searching by keyword:

• "Search Hacker News for recent stories about Rust."
• "Find the most relevant Hacker News stories about LLM fine-tuning."
• "Show me the latest 5 Hacker News stories mentioning WebAssembly."

Searching by date range:

• "What were the top Hacker News stories about OpenAI in April 2026?"
• "Find Hacker News stories about Kubernetes from March 1 to March 31, 2026."

Fetching a specific story:

• "Get the Hacker News story with ID 12345678."

Looking up a user:

• "Show me the Hacker News profile of pg."
• "What is the account info for the user tptacek on Hacker News?"

Development

Dev Container

Open this repository in a Dev Container to get Python 3.12 and uv preinstalled.

The container runs this setup command after creation:

uv sync --extra dev

Tests can be run with:

uv run pytest

Local

uv sync --extra dev
uv run pytest