HackerNews MCP Server

A Model Context Protocol (MCP) server that provides programmatic access to HackerNews content through the official HN Algolia API. This enables AI assistants and other MCP clients to search, retrieve, and analyze HackerNews stories, comments, and user profiles.

Features

• 🔍 Comprehensive Search: Search HackerNews by relevance or date with advanced filtering
• 📰 Content Access: Retrieve stories, comments, and polls with full metadata
• 👤 User Profiles: Access user information, submissions, and comment history
• ⚡ High Performance: Async/await design with connection pooling and retry logic
• 🛡️ Type Safe: Full Pydantic validation and type hints throughout
• 🔧 MCP Compatible: Works with Claude Desktop, Continue, and other MCP clients
• 🌐 Dual Transport: Supports both stdio (local) and HTTP/SSE (cloud) modes
• ☁️ Cloud Ready: Deploy to Railway, fly.io, Render, AWS Lambda, Google Cloud Run

Installation

From PyPI (Recommended)

Stdio mode (default - for local use):

pip install hn-mcp-server

HTTP/SSE mode (for cloud deployment):

pip install hn-mcp-server[http]

From Source

git clone https://github.com/CyrilBaah/hn-mcp-server.git
cd hn-mcp-server
pip install -e .

Development Installation

pip install -e ".[dev]"

Quick Start

Stdio Mode (Local Desktop Clients)

The default mode for local MCP clients like Claude Desktop and Cursor.

Testing the Server:

# Test that the server responds to MCP protocol
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m hn_mcp_server

You should see a JSON response indicating successful initialization.

With MCP Inspector

The MCP Inspector provides a web-based interface for testing and debugging your server:

# Using npx (no installation required)
npx @modelcontextprotocol/inspector python -m hn_mcp_server

# Or install globally
npm install -g @modelcontextprotocol/inspector
mcp-inspector python -m hn_mcp_server

This will open a browser interface where you can:

• Test all available tools interactively
• Inspect requests and responses
• Debug tool parameters and outputs
• View server logs in real-time

With VS Code MCP

Using vscodemcp.com, update your .vscode/mcp.json:

{
  "servers": {
    "hackernews": {
      "command": "python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Note: If you installed in a virtual environment, use the full path to your Python executable:

{
  "servers": {
    "hackernews": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

With Cursor

Or manually update your .cursor/mcp.json:

{
  "servers": {
    "hackernews": {
      "command": "python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Note: If you installed in a virtual environment, use the full path to your Python executable:

{
  "servers": {
    "hackernews": {
      "command": "/path/to/your/venv/bin/python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

With Claude Desktop

Claude Desktop

Add to your Claude Desktop configuration file:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hackernews": {
      "command": "python",
      "args": ["-m", "hn_mcp_server"],
      "env": {
        "LOG_LEVEL": "INFO"
      }
    }
  }
}

Restart Claude Desktop, and the HackerNews tools will be available.

HTTP/SSE Mode (Cloud Deployment)

For deploying to cloud platforms or accessing from remote clients.

Installation:

pip install hn-mcp-server[http]

Running HTTP Server:

# Default: runs on 0.0.0.0:8000
python -m hn_mcp_server --transport http

# Custom host and port
python -m hn_mcp_server --transport http --host 127.0.0.1 --port 3000

Endpoints:

• SSE: http://localhost:8000/sse - MCP communication
• Health: http://localhost:8000/health - Health check

Client Configuration (HTTP):

{
  "mcpServers": {
    "hackernews-remote": {
      "url": "https://your-server.example.com/sse"
    }
  }
}

Docker Deployment:

FROM python:3.11-slim

WORKDIR /app
RUN pip install hn-mcp-server[http]

EXPOSE 8000
CMD ["python", "-m", "hn_mcp_server", "--transport", "http"]

Deploy to Railway/Render/fly.io:

# Set environment variable
TRANSPORT=http

# Start command
python -m hn_mcp_server --transport http --port $PORT

Standalone Usage

The HN client can also be used directly without MCP:

import asyncio
from hn_mcp_server.services import HNClient

async def main():
    async with HNClient() as client:
        # Search for Python stories
        result = await client.search(
            query="python",
            tags=["story"],
            hits_per_page=10
        )
        
        for hit in result.hits:
            print(f"{hit.title} - {hit.points} points")

asyncio.run(main())

See examples/direct_api_usage.py for more examples.

Available Tools

Search Tools

search_hn

Search HackerNews content by relevance (sorted by relevance → points → comments).

{
  "query": "artificial intelligence",
  "tags": ["story"],
  "hits_per_page": 20
}

search_hn_by_date

Search HackerNews content by date (most recent first).

{
  "query": "python",
  "tags": ["story", "show_hn"],
  "hits_per_page": 10
}

get_front_page

Retrieve current HackerNews front page stories.

{
  "page": 0,
  "hits_per_page": 30
}

get_latest_stories

Retrieve most recent HackerNews stories.

{
  "hits_per_page": 20
}

get_latest_comments

Retrieve most recent HackerNews comments.

{
  "hits_per_page": 20
}

search_by_time_range

Search items within a specific time range.

{
  "start_timestamp": 1704067200,
  "end_timestamp": 1736078400,
  "query": "AI",
  "hits_per_page": 10
}

search_by_metrics

Search items with minimum points or comments.

{
  "min_points": 100,
  "min_comments": 50,
  "tags": ["story"]
}

Item Tools

get_item

Retrieve a specific item (story, comment, poll) by ID.

{
  "item_id": 1
}

get_story_comments

Retrieve a story and all its comments (full tree).

{
  "story_id": 39195605
}

User Tools

get_user

Retrieve user profile information.

{
  "username": "pg"
}

get_user_stories

Retrieve all stories submitted by a user.

{
  "username": "pg",
  "hits_per_page": 20
}

get_user_comments

Retrieve all comments by a user.

{
  "username": "pg",
  "hits_per_page": 20
}

Configuration

Configure via environment variables:

# API Configuration
export HN_API_BASE_URL="https://hn.algolia.com/api/v1"  # Default
export HN_REQUEST_TIMEOUT="10"  # Seconds, default: 10
export HN_MAX_RETRIES="3"  # Default: 3

# Logging
export LOG_LEVEL="INFO"  # DEBUG, INFO, WARNING, ERROR

Search Tags

Available tags for filtering:

• Type: story, comment, poll, pollopt
• Special: show_hn, ask_hn, front_page
• Author: author_USERNAME (e.g., author_pg)
• Story: story_ID (e.g., story_12345)

Numeric Filters

Filter by numeric fields:

• created_at_i - Unix timestamp
• points - Story points
• num_comments - Number of comments

Operators: <, <=, =, >, >=

Examples:

• points>100 - Stories with more than 100 points
• created_at_i>1704067200 - Items after Jan 1, 2024
• num_comments>=50 - Items with 50+ comments

Examples

See the examples/ directory for usage examples:

• direct_api_usage.py - Direct API client usage without MCP
• basic_usage.py - MCP client usage (requires MCP client library)
• mcp_config.json - Claude Desktop configuration

Running Examples

# Run direct API example (no MCP client needed)
python examples/direct_api_usage.py

# Run MCP client example (requires mcp library)
python examples/basic_usage.py

The direct API example demonstrates using the HackerNews client library directly, while the basic usage example shows how to interact with the MCP server programmatically.

Development

Setup

# Clone repository
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server

# Create virtual environment (recommended)
python -m venv .venv
source .venv/bin/activate  # On Windows: .venv\Scripts\activate

# Install in development mode with dev dependencies
pip install -e ".[dev]"

Testing the Installation

# Test the MCP server starts correctly
echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m hn_mcp_server

# Run the direct API example
python examples/direct_api_usage.py

Testing

# Run all tests
pytest

# Run unit tests only
pytest tests/unit/

# Run with coverage
pytest --cov=hn_mcp_server --cov-report=html

# Run integration tests (requires internet)
pytest tests/integration/ -m integration

Linting & Formatting

# Format code
ruff format .

# Lint code
ruff check .

# Type checking
mypy src/

Architecture

hn-mcp-server/
├── src/hn_mcp_server/
│   ├── server.py          # MCP server setup
│   ├── models/            # Pydantic data models
│   ├── services/          # API client & rate limiting
│   └── tools/             # MCP tool implementations
├── tests/
│   ├── unit/              # Unit tests
│   ├── integration/       # Integration tests
│   └── contract/          # MCP protocol tests
└── examples/              # Usage examples

API Rate Limits

The HackerNews API has a rate limit of 10,000 requests/hour per IP. The client includes built-in rate limiting to stay within these bounds.

Troubleshooting

Server Not Starting

If the MCP server fails to start:

1. Check Python version: Ensure you're using Python 3.11 or higher

   python --version
   

2. Verify installation: Make sure the package is installed correctly

   pip list | grep hn-mcp-server
   

3. Test server directly: Try initializing the server manually

   echo '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"1.0.0","capabilities":{},"clientInfo":{"name":"test","version":"1.0.0"}}}' | python -m hn_mcp_server
   

Virtual Environment Issues

If using a virtual environment with VS Code or Claude Desktop:

1. Use full path: In your configuration file, use the full path to the Python executable:

   {
     "command": "/full/path/to/.venv/bin/python",
     "args": ["-m", "hn_mcp_server"]
   }
   

2. Find Python path: To get the full path to your virtual environment's Python:

   which python  # On Unix/macOS
   where python  # On Windows
   

MCP Client Examples Not Working

The MCP client examples (basic_usage.py) require the server subprocess to communicate via stdio. If you encounter issues:

1. Use the direct API examples instead (direct_api_usage.py)
2. Ensure you're using sys.executable in the client configuration (already updated in the examples)

API Errors

If you encounter API errors:

1. Check network connectivity: Ensure you can reach hn.algolia.com
2. Rate limiting: Wait if you've exceeded the 10,000 requests/hour limit
3. Invalid item ID: Ensure the item ID exists on HackerNews

Publishing to PyPI

Prerequisites

1. Install build tools:

   pip install build twine
   

2. Ensure you have PyPI credentials (create account at pypi.org)

Quick Publish (Automated)

Use the release script for automated publishing:

# Publish to PyPI (production)
python scripts/release.py 1.0.1

# Or using Make
make publish       # PyPI

The script will automatically:

• Update version numbers
• Run tests and linting
• Build the package
• Create git tag
• Publish to PyPI

See docs/PUBLISHING.md for detailed instructions.

Manual Build and Publish

1. Update version in pyproject.toml:

   [project]
   version = "1.1.0"  # Increment appropriately
   

2. Clean previous builds:

   rm -rf dist/ build/ *.egg-info
   

3. Build the package:

   python -m build
   

4. Check the distribution:

   twine check dist/*
   

5. Upload to PyPI:

   twine upload dist/*
   

6. Create a git tag:

   git tag -a v1.1.0 -m "Release version 1.1.0"
   git push origin v1.1.0
   

Using API Tokens (Recommended)

Instead of username/password, use API tokens:

1. Generate token at pypi.org/manage/account/token/
2. Create ~/.pypirc:

   [pypi]
   username = __token__
   password = pypi-AgEIcHlwaS5vcmc...
   

Contributing

Contributions are welcome! Please:

1. Fork the repository
2. Create a feature branch (git checkout -b feature/amazing-feature)
3. Commit your changes (git commit -m 'Add amazing feature')
4. Push to the branch (git push origin feature/amazing-feature)
5. Open a Pull Request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Acknowledgments

• HackerNews for the API
• Algolia for powering the HN search
• Model Context Protocol specification

Support

• 📖 Documentation
• 🚀 Quick Start Guide
• 🐛 Issue Tracker
• 💬 Discussions

---

Available on PyPI: pip install hn-mcp-server

---

Note: This is an unofficial third-party client and is not affiliated with Y Combinator or HackerNews.