You can run a Python-based MCP server that provides programmatic access to Hacker News data. This server exposes a set of tools for fetching items, stories, users, and related content, with options for human-friendly Markdown output or machine-friendly JSON. It supports efficient batch requests, pagination, and graceful error handling, making it easy to build AI-assisted workflows that explore Hacker News data.

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.

## Available tools

### 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.