📰 Hacker News MCP Server

A Model Context Protocol (MCP) server that provides tools to fetch and interact with Hacker News content. This server enables AI assistants to access real-time Hacker News data including top stories, story details, comments, and search functionality.

🚀 Features

🛠️ Available Tools

get_top_stories - Fetch the latest top stories from Hacker News
- Configurable count (1-100 stories)
- Optional text content inclusion
- Returns story metadata including title, URL, score, author, and comment count
get_story_details - Get detailed information about a specific story
- Fetch complete story metadata
- Optional comment inclusion with threaded structure
- Optional markdown content extraction from linked articles
get_story_comments - Retrieve popular comments for a story
- Configurable minimum score filtering
- Adjustable comment thread depth (1-10 levels)
- Limit number of comments returned (1-100)
- Formatted as readable text with thread structure
search_stories - Search recent stories by keywords
- Search through story titles, content, and URLs
- Configurable time range (1-168 hours)
- Limit results (1-50 stories)

📋 Prerequisites

Node.js 18+
npm or yarn
An MCP-compatible client (like Claude Desktop)

🔧 Installation

1. Clone the repository

git clone https://github.com/yourusername/hackernews-mcp.git
cd hackernews-mcp

2. Install dependencies

npm install

3. Build the server

npm run build

🎯 Usage

With Claude Desktop

Add the server to your Claude Desktop configuration:

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

{
  "mcpServers": {
    "hackernews-mcp": {
      "command": "node",
      "args": ["/path/to/hackernews-mcp/build/index.js"]
    }
  }
}

With Other MCP Clients

The server communicates via stdio and can be used with any MCP-compatible client:

node build/index.js

🔍 Example Usage

Once connected, you can ask your AI assistant things like:

"What are the top stories on Hacker News today?"
"Get details about Hacker News story 12345678"
"Show me comments for that viral AI story"
"Search for recent stories about TypeScript"

🛠️ Development

Build the project

npm run build

Watch mode for development

npm run watch

Lint and format the code

npm run lint
npm run format

Run the MCP Inspector

For debugging and testing:

npm run inspector

This will start the MCP Inspector, providing a web interface to test the server's tools and inspect the communication.

📦 Code Quality & Contributing

Code Quality:
This project enforces code quality and style using ESLint and Prettier. All code is checked in CI (GitHub Actions) and must pass linting and formatting before merging.
Type Safety:
All tool handlers use explicit type guards for runtime argument validation and robust TypeScript types.
CI/CD:
Every push and pull request runs the full build, lint, and (future) test suite via GitHub Actions.
How to Contribute:
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. Run npm run lint and npm run format before pushing
5. Push to the branch (git push origin feature/amazing-feature)
6. Open a Pull Request

📚 API Reference

get_top_stories

{
  count?: number;        // Number of stories (1-100, default: 30)
  include_text?: boolean; // Include story text content (default: false)
}

get_story_details

{
  story_id: number;           // Required: HN story ID
  include_comments?: boolean; // Include comments (default: false)
  include_markdown?: boolean; // Extract article as markdown (default: false)
}

get_story_comments

{
  story_id: number;    // Required: HN story ID
  min_score?: number;  // Minimum comment score (default: 1)
  max_depth?: number;  // Max thread depth (1-10, default: 3)
  limit?: number;      // Max comments (1-100, default: 20)
}

search_stories

{
  query: string;              // Required: Search keywords
  limit?: number;             // Max results (1-50, default: 20)
  time_range_hours?: number;  // Hours to search back (1-168, default: 24)
}

🏗️ Architecture

The server is built with:

TypeScript for type safety and developer experience
@modelcontextprotocol/sdk for MCP protocol implementation
axios for HTTP requests to Hacker News API
jsdom and turndown for HTML to Markdown conversion
private-ip for security (blocks private IP access)

Key Components

src/index.ts - Main server implementation with tool handlers
src/fetcher.ts - Utility class for fetching and converting web content
build/ - Compiled JavaScript output (auto-generated)

🔒 Security

Blocks requests to private IP addresses to prevent local network access
Rate limiting through Hacker News API natural limits
Input validation for all tool parameters
Error handling and graceful degradation

📜 License

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

🙏 Acknowledgments

Hacker News for providing the excellent API
Model Context Protocol for the standard
The open source community for the amazing tools and libraries

📞 Support

If you encounter any issues or have questions:

Check the Issues page
Use the MCP Inspector for debugging: npm run inspector
Create a new issue with detailed information about your problem

Made with ❤️ for the MCP community