Skip to main content
Glama

Hacker News MCP Server

by az9713
GitHub
Python
OverviewInspectNewEndpointsSchemaRelated ServersReviewsScore
Need Help?View Source CodeReport Issue

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:

    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)

  1. Locate your Claude Desktop config file:

    %APPDATA%\Claude\claude_desktop_config.json

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

  1. Restart Claude Desktop

  2. 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"

hn_get_new_stories

Get newest stories in chronological order.

Parameters: Same as hn_get_top_stories

hn_get_best_stories

Get best stories by HN's algorithm.

Parameters: Same as hn_get_top_stories

hn_get_ask_stories

Get latest Ask HN posts.

Parameters: Same as hn_get_top_stories

hn_get_show_stories

Get latest Show HN posts.

Parameters: Same as hn_get_top_stories

hn_get_job_stories

Get latest job postings.

Parameters: Same as hn_get_top_stories

hn_get_user

Get user profile information.

Parameters:

  • username (required): Case-sensitive username

  • response_format: "markdown" (default) or "json"

  • include_submissions: Include full submission list (default: false)

Example:

{ "username": "pg", "response_format": "markdown", "include_submissions": false }

hn_get_max_item_id

Get the current maximum item ID.

Parameters: None

Troubleshooting

"python: command not found"

Solution: Python is not in your PATH.

PowerShell:

# Find Python installation Get-Command python # If not found, reinstall Python with "Add to PATH" checked

Git Bash:

# Check if Python is installed which python # Add Python to PATH temporarily export PATH="/c/Users/YourUsername/AppData/Local/Programs/Python/Python311:$PATH"

"No module named 'mcp'"

Solution: Install dependencies in the virtual environment:

# Make sure virtual environment is activated (you should see (venv) in prompt) source venv/Scripts/activate # Git Bash # or .\venv\Scripts\Activate.ps1 # PowerShell # Install dependencies pip install mcp httpx pydantic

"Permission denied" when activating virtual environment (PowerShell)

Solution: Enable script execution:

Set-ExecutionPolicy -ExecutionPolicy RemoteSigned -Scope CurrentUser

Server appears to hang when running

This is normal behavior! MCP servers are long-running processes that wait for requests over stdio. They don't exit immediately. To test if it's working:

  1. Run python hackernews_mcp.py --help - should show help

  2. Configure it in Claude Desktop and use it through Claude

  3. Use Ctrl+C to stop the server if running it manually

Claude Desktop doesn't show HN tools

Checklist:

  1. Verify JSON syntax in claude_desktop_config.json (use a JSON validator)

  2. Use double backslashes in Windows paths: C:\\Users\\...

  3. Use full absolute paths, not relative paths

  4. Restart Claude Desktop after config changes

  5. Check Claude Desktop logs (usually in %APPDATA%\Claude\logs)

"Rate limit exceeded" errors

The Hacker News API has no official rate limit, but if you're making too many requests:

  1. Use limit parameter to fetch fewer items

  2. Use detail_level: "concise" to reduce API calls

  3. Add delays between requests if needed

API Documentation

This server uses the official Hacker News Firebase API:

  • Base URL: https://hacker-news.firebaseio.com/v0/

  • Documentation: See docs/README.md in this repository

  • Source: Hacker News API on GitHub

Architecture

  • Framework: FastMCP (official MCP Python SDK)

  • HTTP Client: httpx (async)

  • Validation: Pydantic v2

  • Transport: stdio (standard input/output)

Key Features:

  • Async/await for all I/O operations

  • Parallel batch fetching for efficiency

  • Comprehensive error handling

  • Character limit enforcement (25,000 chars)

  • Pagination support

  • Input validation with detailed constraints

Development

Running Tests

# Activate virtual environment first source venv/Scripts/activate # Git Bash # or .\venv\Scripts\Activate.ps1 # PowerShell # Test imports python -c "from hackernews_mcp import mcp; print('Import successful')" # Test server help python hackernews_mcp.py --help

Code Structure

hackernews_mcp.py ├── Constants (API_BASE_URL, CHARACTER_LIMIT, etc.) ├── Enums (ResponseFormat, DetailLevel) ├── Pydantic Models (ItemInput, StoryListInput, UserInput) ├── Shared Utilities │ ├── _fetch_from_api() - HTTP requests │ ├── _fetch_items_batch() - Parallel fetching │ ├── _format_timestamp() - Time formatting │ ├── _format_item_markdown() - Markdown output │ ├── _format_item_json() - JSON output │ ├── _handle_api_error() - Error handling │ └── _check_truncation() - Character limit enforcement └── Tools (9 @mcp.tool decorated functions)

License

This MCP server is provided as-is for use with the Hacker News API. The Hacker News API is provided by Y Combinator.

Credits

  • Hacker News API: Y Combinator

  • MCP Protocol: Anthropic

  • Server Implementation: Created with Claude Code with skill mcp-builder

Support

For issues or questions:

  1. Check the Troubleshooting section above

  2. Review the API documentation in docs/README.md

  3. Verify your Python and dependency versions

  4. Check Claude Desktop logs for detailed error messages

Version

Version: 1.0.0 Last Updated: 2025-10-18

This server cannot be installed

-
security - not tested
F
license - not found
-
quality - not tested

How are these scores calculated?

remote-capable server

The server can be hosted and run remotely because it primarily relies on remote services or has no dependency on the local environment.

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

  1. Features
    1. Requirements
      1. Installation
        1. Step 1: Install Python
        2. Step 2: Create a Virtual Environment (Recommended)
        3. Step 3: Install Dependencies
        4. Step 4: Test the Server
      2. Configuration
        1. For Claude Desktop (Windows)
        2. For Other MCP Clients
      3. Usage Examples
        1. Get Top Stories
        2. Get Story Details
        3. Search for User
        4. Get Ask HN Posts
        5. Browse Job Postings
      4. Tool Reference
        1. hn_get_item
        2. hn_get_top_stories
        3. hn_get_new_stories
        4. hn_get_best_stories
        5. hn_get_ask_stories
        6. hn_get_show_stories
        7. hn_get_job_stories
        8. hn_get_user
        9. hn_get_max_item_id
      5. Troubleshooting
        1. "python: command not found"
        2. "No module named 'mcp'"
        3. "Permission denied" when activating virtual environment (PowerShell)
        4. Server appears to hang when running
        5. Claude Desktop doesn't show HN tools
        6. "Rate limit exceeded" errors
      6. API Documentation
        1. Architecture
          1. Key Features:
        2. Development
          1. Running Tests
          2. Code Structure
        3. License
          1. Credits
            1. Support
              1. Version

                New MCP Servers

                MCP directory API

                We provide all the information about MCP servers via our MCP API.

                curl -X GET 'https://glama.ai/api/mcp/v1/servers/az9713/claude_skill_hn_mcp_server'

                If you have feedback or need assistance with the MCP directory API, please join our Discord server