HackerNews MCP Server

🚀 Model Context Protocol server for interacting with HackerNews

Enable AI agents and developers to search, retrieve, and analyze HackerNews content through the Model Context Protocol (MCP). This server provides tools for advanced search, front page retrieval, detailed post access with comment trees, and user profile lookups.

✨ Features

• 🔍 Advanced Search - Find posts with keyword search, filters (author, date, points, comments), and flexible sorting

• 📰 Front Page Access - Retrieve current HackerNews front page content with pagination

• 💬 Full Comment Trees - Access complete discussion threads with nested comment structure

• 👤 User Profiles - Look up user information including karma, account age, and bio

• ⚡ Rate Limiting - Automatic rate limiting respecting HN API constraints (10,000 req/hour)

• 🛡️ Type Safety - Built with TypeScript strict mode and comprehensive validation

• 📚 Well Documented - Complete API documentation and usage examples

• ✅ Thoroughly Tested - 90%+ test coverage with contract, integration, and unit tests

📋 Table of Contents

• Installation

• Quick Start

• Usage Examples

• Available Tools

• Configuration

• Development

• Contributing

• License

📦 Installation

Prerequisites

• Node.js 22.0.0 or higher

• npm 10.0.0 or higher

Install via npm

Install from Source

🚀 Quick Start

With Claude Desktop

Add to your claude_desktop_config.json:

Config file locations:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

• Windows: %APPDATA%\Claude\claude_desktop_config.json

• Linux: ~/.config/Claude/claude_desktop_config.json

After configuration, restart Claude Desktop. The HackerNews tools will be available in your conversations.

With VS Code + GitHub Copilot

Add to your VS Code settings.json:

Test Installation

The server will start and wait for MCP client connections via stdio.

💡 Usage Examples

Example 1: Search for AI/ML Posts

Natural Language (in Claude):

Example 2: Browse Front Page

Natural Language:

Example 3: Read Discussion

Natural Language:

Example 4: Research a User

Natural Language:

Example 5: Advanced Filtering

Natural Language:

For more detailed examples, see the Quickstart Guide.

🛠️ Available Tools

search_posts

Search HackerNews posts with advanced filtering options.

Parameters:

• query (string, optional) - Search keywords

• tags (array, optional) - Content type filters: story, comment, poll, show_hn, ask_hn, front_page

• author (string, optional) - Filter by username

• storyId (number, optional) - Filter comments by story ID

• minPoints, maxPoints (number, optional) - Points thresholds

• minComments, maxComments (number, optional) - Comment count thresholds

• dateAfter, dateBefore (string, optional) - Date range filters (ISO 8601)

• sortByDate (boolean, optional) - Sort by date (true) or relevance (false, default)

• page (number, optional) - Page number (0-indexed, default: 0)

• hitsPerPage (number, optional) - Results per page (1-100, default: 20)

get_front_page

Retrieve current HackerNews front page posts.

Parameters:

• page (number, optional) - Page number (0-indexed, default: 0)

• hitsPerPage (number, optional) - Results per page (1-30, default: 30)

get_post

Get full details of a specific post including comment tree.

Parameters:

• postId (string, required) - HackerNews post ID

get_user

Retrieve user profile information.

Parameters:

• username (string, required) - HackerNews username (1-15 characters)

⚙️ Configuration

Rate Limiting

The server automatically respects HackerNews API's rate limit of 10,000 requests per hour per IP address.

• Tracks requests using token bucket algorithm

• Logs warnings at 80%, 90%, 95% usage

• Returns rate limit error when exceeded

• Automatically refills tokens over time

Error Handling

All tools return structured errors:

👨‍💻 Development

Setup

Development Workflow

Testing

The project follows Test-Driven Development (TDD) with three test layers:

• Contract Tests: Validate external API response schemas

• Integration Tests: Test tool workflows end-to-end with mocked APIs

• Unit Tests: Test individual functions in isolation

Coverage Requirement: 90% minimum for lines, functions, branches, and statements.

Project Structure

Code Style

• Language: TypeScript 5.x with strict mode enabled

• Linter: Biome (no ESLint or Prettier)

• Formatting: 2-space indentation, 100-character line width, double quotes

• Type Safety: No any types, explicit return types on exported functions

🤝 Contributing

Contributions are welcome! Please follow these guidelines:

1. Fork the repository

2. Create a feature branch: git checkout -b feature/my-feature

3. Follow TDD: Write tests first, then implementation

4. Ensure tests pass: npm test

5. Ensure linting passes: npm run lint

6. Maintain coverage: Keep at 90%+

7. Commit changes: git commit -m "Add my feature"

8. Push to branch: git push origin feature/my-feature

9. Open a Pull Request

Development Principles

This project follows strict quality standards documented in .specify/memory/constitution.md:

• Code Quality First: TypeScript strict mode, no any types

• Test-Driven Development: Tests before implementation

• Documentation-First: Complete docs for all features

• Latest Stable Versions: Up-to-date dependencies

• Reuse Over Reinvention: Leverage existing libraries

📚 Documentation

• Feature Specification - Detailed requirements and user stories

• Implementation Plan - Technical design and architecture

• Research Documentation - Technical decisions and rationale

• Data Model - Entity schemas and validation rules

• Quickstart Guide - Usage examples and reference

• Tool Contracts - MCP tool definitions

📝 License

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

🙏 Acknowledgments

• HackerNews - Community and content

• HN Algolia API - Search API powering this server

• Model Context Protocol - MCP specification and SDK

• Anthropic - Claude and MCP development

🐛 Support

• Issues: GitHub Issues

• Discussions: GitHub Discussions

• HN API Docs: hn.algolia.com/api

• MCP Docs: modelcontextprotocol.io

Built with ❤️ using TypeScript, MCP SDK, and Biome