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
- Clone this repository:
git clone <repository-url>
cd hn-mcp-server-vibe
- Install dependencies:
npm install
- 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 storiescomment- Commentspoll- Pollspollopt- Poll optionsshow_hn- Show HN postsask_hn- Ask HN postsfront_page- Currently on front pageauthor_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/upvotesnum_comments- Number of comments
Operators: <, <=, =, >, >=
Examples:
points>100- More than 100 pointscreated_at_i>1672531200- After specific datepoints>=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 itemsnbHits- Total number of matchesnbPages- Total number of pagespage- Current page numberhitsPerPage- 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 installto ensure all dependencies are installed - Run
npm run buildto 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