claude_skill_hn_mcp_server

HackerNews MCP Server created with Claude Skill mcp-builder

0 stars PythonAI & Machine Learning Updated Oct 19, 2025

Documentation

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:

1. Download Python from python.org

2. Important: During installation, check "Add Python to PATH"

3. Verify installation:

bash

python --version

Step 2: Create a Virtual Environment (Recommended)

Using a virtual environment keeps dependencies isolated:

PowerShell:

powershell

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

Git Bash:

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

bash

pip install --upgrade pip
pip install mcp httpx pydantic

Verify installation:

bash

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

Step 4: Test the Server

Verify the server can run:

bash

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)

1. Locate your Claude Desktop config file:

code

%APPDATA%\Claude\claude_desktop_config.json

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

PowerShell users:

json

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

Git Bash users:

json

{
  "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`

3. Restart Claude Desktop

4. Verify the connection:

For Other MCP Clients

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

bash

python /path/to/hackernews_mcp.py

Usage Examples

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

Get Top Stories

code

Show me the top 10 stories on Hacker News right now

Get Story Details

code

Get details about HN story with ID 8863

Search for User

code

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

Get Ask HN Posts

code

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

Browse Job Postings

code

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:

json

{
  "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"