MCP Servers

Hacker News MCP Server

Enables AI assistants to access Hacker News content through 9 comprehensive tools for fetching stories, comments, user profiles, and job postings. Supports flexible output formats, pagination, and various story categories (top, new, best, Ask HN, Show HN).

README

Hacker News MCP Server

A Model Context Protocol (MCP) server that provides access to the Hacker News API. This server allows AI assistants like Claude to fetch stories, comments, user profiles, and other content from Hacker News.

Created with Claude Code using Claude skill mcp-builder.

Features

9 Comprehensive Tools for accessing Hacker News data:
- hn_get_item - Get any item (story, comment, job, poll) by ID
- hn_get_top_stories - Get current front page stories
- hn_get_new_stories - Get newest stories
- hn_get_best_stories - Get best stories of all time
- hn_get_ask_stories - Get Ask HN posts
- hn_get_show_stories - Get Show HN posts
- hn_get_job_stories - Get job postings
- hn_get_user - Get user profile information
- hn_get_max_item_id - Get the latest item ID
Flexible Output Formats: Both Markdown (human-readable) and JSON (machine-readable)
Pagination Support: Efficiently browse large result sets
Detail Levels: Choose between concise summaries or detailed information
Rate Limit Handling: Graceful error handling with helpful messages
Character Limits: Automatic truncation for large responses
Parallel Fetching: Efficient batch requests for multiple items

Requirements

Python 3.8+ (tested on Python 3.10+)
Windows 10/11 (compatible with PowerShell and Git Bash)

Installation

Step 1: Install Python

If you don't have Python installed:

Download Python from python.org
Important: During installation, check "Add Python to PATH"
Verify installation:
```
python --version
```

Step 2: Create a Virtual Environment (Recommended)

Using a virtual environment keeps dependencies isolated:

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

You should see (venv) in your terminal prompt after activation.

Step 3: Install Dependencies

pip install --upgrade pip
pip install mcp httpx pydantic

Verify installation:

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

Step 4: Test the Server

Verify the server can run:

python hackernews_mcp.py --help

You should see FastMCP help output. The server will appear to hang - this is normal! Press Ctrl+C to stop it.

Configuration

For Claude Desktop (Windows)

Locate your Claude Desktop config file:

%APPDATA%\Claude\claude_desktop_config.json

Open it in a text editor and add the Hacker News MCP server:

PowerShell users:

{
  "mcpServers": {
    "hackernews": {
      "command": "/path/to/python.exe",
      "args": [
        "/path/to/hackernews_mcp.py"
      ]
    }
  }
}

Git Bash users:

{
  "mcpServers": {
    "hackernews": {
      "command": "/path/to/python.exe",
      "args": [
        "/path/to/hackernews_mcp.py"
      ]
    }
  }
}

Important Notes:

Use double backslashes (\\) in the JSON file paths
Use the full absolute paths to both python.exe and hackernews_mcp.py
If you have other MCP servers, add this as another entry in mcpServers

Restart Claude Desktop
Verify the connection:
- Open Claude Desktop
- Look for a "hammer" or "tools" icon indicating MCP servers are connected
- Ask Claude: "What Hacker News tools do you have available?"

For Other MCP Clients

The server uses stdio transport by default. Configure your MCP client to run:

python /path/to/hackernews_mcp.py

Usage Examples

Once configured, you can ask Claude to use the Hacker News tools:

Get Top Stories

Show me the top 10 stories on Hacker News right now

Get Story Details

Get details about HN story with ID 8863

Search for User

What's the profile for HN user 'pg'?

Get Ask HN Posts

Show me the latest Ask HN questions with at least 50 comments

Browse Job Postings

What are the latest 5 job postings on HN?

Tool Reference

hn_get_item

Get complete details for any HN item (story, comment, job, poll).

Parameters:

item_id (required): The item ID number
response_format: "markdown" (default) or "json"
detail_level: "detailed" (default) or "concise"

Example:

{
  "item_id": 8863,
  "response_format": "markdown",
  "detail_level": "detailed"
}

hn_get_top_stories

Get current front page stories.

Parameters:

limit: Max stories to return (1-100, default: 30)
offset: Skip this many stories (default: 0)
response_format: "markdown" (default) or "json"
detail_level: "concise" (default) or "detailed"