HackerNews MCP Server

A Model Context Protocol (MCP) server that provides comprehensive access to the HackerNews API. This server enables AI assistants and other MCP clients to search, retrieve, and interact with HackerNews content including stories, comments, polls, users, and more.

Features

This MCP server exposes 15 tools covering all available HackerNews API endpoints:

Search & Discovery Tools

• search-posts - Search posts by relevance (sorted by relevance, points, then comments)
• search-posts-by-date - Search posts sorted by date (most recent first)
• search-by-url - Find posts linking to a specific URL
• search-by-time-range - Search posts within a specific time range

Content Retrieval Tools

• get-front-page - Get all stories currently on the HackerNews front page
• get-latest-stories - Get the most recent stories
• get-latest-comments - Get the most recent comments
• get-show-hn - Get "Show HN" posts (user projects)
• get-ask-hn - Get "Ask HN" posts (questions)
• get-polls - Get latest polls
• get-top-stories - Get stories with minimum points threshold

Item & User Tools

• get-item - Get a specific item (story, comment, poll) by ID
• get-user - Get user information and karma
• get-posts-by-author - Get all posts by a specific author
• get-story-comments - Get all comments for a specific story

Installation

Prerequisites

• Node.js 18 or higher
• npm or yarn

Setup

1. Clone this repository:

git clone <repository-url>
cd hn-mcp-server-vibe

2. Install dependencies:

npm install

3. Build the server:

npm run build

Usage

Running the Server Directly

You can run the server directly with Node.js:

npm start

Or during development:

npm run dev

Configuring with Claude Desktop

To use this server with Claude Desktop, add the following configuration to your Claude Desktop config file:

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

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

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

Replace /absolute/path/to/hn-mcp-server-vibe with the actual path to your installation.

Configuring with Other MCP Clients

For other MCP clients that support stdio transport, configure them to spawn:

node /path/to/hn-mcp-server-vibe/build/index.js

API Examples

Search for Posts

// Search for AI-related stories
{
  "tool": "search-posts",
  "arguments": {
    "query": "artificial intelligence",
    "tags": "story",
    "page": 0,
    "hitsPerPage": 20
  }
}

Get Front Page Stories

{
  "tool": "get-front-page",
  "arguments": {
    "hitsPerPage": 30
  }
}

Get User Information

{
  "tool": "get-user",
  "arguments": {
    "username": "pg"
  }
}

Get Top Stories

// Get stories with at least 500 points
{
  "tool": "get-top-stories",
  "arguments": {
    "minPoints": 500,
    "hitsPerPage": 10
  }
}

Search by Time Range

// Get stories from the last 24 hours
{
  "tool": "search-by-time-range",
  "arguments": {
    "tags": "story",
    "startTime": 1728691200,  // Unix timestamp
    "endTime": 1728777600,     // Unix timestamp
    "hitsPerPage": 20
  }
}

Available Tags

When using search tools, you can filter by the following tags:

• story - Regular stories
• comment - Comments
• poll - Polls
• pollopt - Poll options
• show_hn - Show HN posts
• ask_hn - Ask HN posts
• front_page - Currently on front page
• author_USERNAME - Posts by specific author (e.g., author_pg)
• story_ID - Comments for specific story (e.g., story_1234)

Tags can be combined with commas (AND) or parentheses for OR: author_pg,(story,poll)

Available Numeric Filters

For advanced filtering:

• created_at_i - Creation timestamp (Unix seconds)
• points - Number of points/upvotes
• num_comments - Number of comments

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

Examples:

• points>100 - More than 100 points
• created_at_i>1672531200 - After specific date
• points>=50,num_comments>10 - Multiple conditions

Response Format

All tools return structured data with:

• content - Text representation of the response
• structuredContent - Parsed JSON object for programmatic access

Search results include:

• hits - Array of matching items
• nbHits - Total number of matches
• nbPages - Total number of pages
• page - Current page number
• hitsPerPage - Results per page

Rate Limits

The HackerNews API limits requests to 10,000 per hour per IP address. This server does not implement additional rate limiting, so clients should be mindful of this constraint.

Development

Project Structure

hn-mcp-server-vibe/
├── src/
│   └── index.ts          # Main server implementation
├── build/                 # Compiled JavaScript output
├── package.json
├── tsconfig.json
└── README.md

Building

npm run build

Running in Development

npm run dev

API Reference

Full HackerNews API documentation: https://hn.algolia.com/api

License

MIT

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

Troubleshooting

Server not connecting

• Ensure the build directory exists and contains compiled JavaScript
• Check that Node.js version is 18 or higher
• Verify the absolute path in your MCP client configuration

No results returned

• Check your search query and filters
• Verify the API is accessible: https://hn.algolia.com/api
• Check rate limits haven't been exceeded

TypeScript errors

• Run npm install to ensure all dependencies are installed
• Run npm run build to compile TypeScript

Support

For issues specific to this MCP server, please open an issue on the repository.

For questions about the Model Context Protocol, see: https://modelcontextprotocol.io

For questions about the HackerNews API, see: https://hn.algolia.com/api