Hacker News MCP Server

How to use

Start the MCP server locally and connect to it from your MCP client. The server runs as a long‑running stdio service, so you initialize it and then issue requests through your client to fetch Hacker News data. You can query front page stories, newest or best stories, Ask HN and Show HN posts, jobs, or specific users. Choose output as Markdown for human readability or JSON for machine processing, and use pagination to browse large result sets.

Practical workflows you can perform include: listing the current top stories, retrieving details for a specific story by its ID, exploring a user’s profile, and batching multiple item fetches for performance.

How to install

Prerequisites you need before starting are Python 3.8 or newer.

Step 1: Install Python if you don’t have it already.

# Verify Python is installed
python --version

Step 2: Create a virtual environment to isolate dependencies.

# PowerShell
cd /path/to/claude_skill_create_hn_mcp_server
python -m venv venv
.\venv\Scripts\Activate.ps1

# Git Bash
cd /path/to/claude_skill_create_hn_mcp_server
python -m venv venv
source venv/Scripts/activate

Step 3: Install dependencies in the virtual environment.

pip install --upgrade pip
pip install mcp httpx pydantic

Step 4: Verify the MCP server is installed correctly.

python -c "from mcp.server.fastmcp import FastMCP; print('MCP installed successfully')"

Step 5: Run and test the server.

python hackernews_mcp.py --help
```
You may see a temporary wait state, which is expected for a long-running service. To stop it, press Ctrl+C.

Configuration and usage notes

Configure your MCP client or Claude Desktop to connect to the local stdio server. The common runtime command shown for a local setup is to run the server with Python and provide the path to the script.

Example runtime when using Claude Desktop or another MCP client that executes locally:

{
  "mcpServers": {
    "hackernews": {
      "command": "python",
      "args": ["hackernews_mcp.py"]
    }
  }
}

Troubleshooting

If you encounter issues, try these steps in order.

• Check with: Get-Command python in PowerShell
• Reinstall Python with Add to PATH selected

If you see an error about missing modules, re-activate your virtual environment and reinstall dependencies.

# Reactivate (example for Git Bash)
source venv/Scripts/activate
pip install mcp httpx pydantic

API and data basics

The server exposes tools to retrieve items, lists of stories, and user information from Hacker News. Output can be formatted as Markdown for humans or JSON for programs. You can fetch with pagination and request concise or detailed results to control payload size.

Key API surface you can access includes: getting any item by ID, getting top/new/best/Ask HN/Show HN/job stories, fetching user profiles, and obtaining the latest item ID.

hn_get_item

Get complete details for any Hacker News item (story, comment, job, poll) by its ID, with options for Markdown or JSON output and detailed or concise detail levels.

hn_get_top_stories

Retrieve current front page stories with options to limit, offset, and choose output format and detail level.

hn_get_new_stories

Retrieve the newest stories in chronological order with similar parameters as hn_get_top_stories.

hn_get_best_stories

Retrieve best stories based on Hacker News ranking algorithm with pagination and output options.

hn_get_ask_stories

Retrieve latest Ask HN posts with configurable pagination and output formats.

hn_get_show_stories

Retrieve latest Show HN posts with configurable pagination and output formats.

hn_get_job_stories

Retrieve latest job postings with pagination and output options.

hn_get_user

Fetch user profile information by username, with optional submission lists and output format.

hn_get_max_item_id

Return the current maximum item ID available on Hacker News.