HackerNews MCP Server
Provides programmatic access to Hacker News content via the HN Algolia API, allowing for searching stories and comments, browsing the front page, and retrieving detailed user profiles and nested comment trees.
Click on "Deploy Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type
@followed by the MCP server name and your instructions, e.g., "@HackerNews MCP Server show me the top stories about AI from today"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
HackerNews MCP Server
A Model Context Protocol (MCP) server that provides programmatic access to Hacker News content via the HN Algolia API. This server enables AI assistants like Claude to search stories, retrieve comments, access user profiles, and explore the HN front page in real-time.
Features
β 9 MCP Tools for comprehensive HN access
π Search: Stories by relevance or date, comments with filters
π° Browse: Front page, latest stories, Ask HN, Show HN posts
π€ Details: Retrieve specific stories with nested comments and user profiles
β‘ Rate Limiting: Respects HN API limits (10,000 req/hr)
π‘οΈ Type-Safe: Full TypeScript with strict mode
π Observable: Structured JSON logging with correlation IDs
π§ͺ Tested: Unit, integration, and contract tests
Related MCP server: HackerNews MCP Server
Installation
NPM (when published)
npm install -g hn-mcp-serverFrom Source
git clone https://github.com/YOUR_USERNAME/hn-mcp-server.git
cd hn-mcp-server
npm install
npm run build
npm linkQuick Start (VS Code)
The fastest way to get started is with VS Code and GitHub Copilot:
Clone and build:
git clone <your-repo-url> cd hn-mcp-server npm install npm run buildOpen in VS Code:
code .Reload VS Code (Ctrl+Shift+P β "Developer: Reload Window")
Follow the complete setup checklist: docs/VSCODE_CHECKLIST.md
Open Copilot Chat and try:
@workspace What MCP tools are available?or
Show me the top stories from Hacker News
π Step-by-step setup guide: docs/VSCODE_CHECKLIST.md
π For detailed VS Code setup instructions, see docs/VSCODE_SETUP.md
β οΈ Tools not appearing? See docs/TROUBLESHOOTING_VSCODE.md
π‘ Tip: MCP support in VS Code is experimental. For the best experience, use Claude Desktop (see configuration below).
Configuration
VS Code with GitHub Copilot
The easiest way to use this server is directly in VS Code with GitHub Copilot:
Build the server:
npm run buildConfiguration is already set up in
.vscode/mcp.json:{ "hackernews": { "command": "node", "args": ["${workspaceFolder}/dist/index.js"], "env": { "DEBUG": "0" } } }Reload VS Code or restart the Copilot extension
Test it by asking Copilot:
"Show me the top stories from Hacker News"
"Search HN for stories about AI"
"Get the user profile for 'pg'"
Claude Desktop
Add to your Claude Desktop configuration:
macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json
Linux: ~/.config/claude/claude_desktop_config.json
{
"mcpServers": {
"hackernews": {
"command": "hn-mcp-server"
}
}
}Or if installed from source:
{
"mcpServers": {
"hackernews": {
"command": "node",
"args": ["/path/to/hn-mcp-server/dist/index.js"]
}
}
}Restart Claude Desktop to activate the server.
Available Tools
1. search_stories
Search HN stories by relevance with advanced filtering.
{
query: "artificial intelligence", // Search term
tags: "story,front_page", // Filter by tags
numericFilters: "points>=100", // Minimum points
page: 0, // Pagination
hitsPerPage: 20 // Results per page
}2. search_by_date
Search stories/comments sorted by date (most recent first).
{
query: "TypeScript",
tags: "story",
numericFilters: "created_at_i>1640000000", // Unix timestamp
page: 0,
hitsPerPage: 20
}3. search_comments
Search comments with optional story/author filtering.
{
query: "React hooks",
tags: "author_pg", // Filter by author
sortByDate: false, // Sort by relevance
page: 0,
hitsPerPage: 20
}4. get_front_page
Retrieve current HN front page stories.
{
page: 0,
hitsPerPage: 30
}5. get_latest_stories
Get most recently submitted stories.
{
page: 0,
hitsPerPage: 20
}6. get_ask_hn
Retrieve Ask HN posts (community questions).
{
page: 0,
hitsPerPage: 20
}7. get_show_hn
Retrieve Show HN posts (project showcases).
{
page: 0,
hitsPerPage: 20
}8. get_story
Get a specific story by ID with full nested comment tree.
{
id: 8863 // Famous "How to Start a Startup" post
}9. get_user
Retrieve user profile by username.
{
username: "pg" // Paul Graham
}Example Usage in Claude
Search for AI stories:
Show me the top stories about AI from Hacker NewsGet front page:
What's currently on the Hacker News front page?Find user information:
Tell me about the HN user 'pg'Advanced search:
Find recent stories about TypeScript with at least 50 pointsDevelopment
Prerequisites
Node.js 20 LTS or higher
npm or yarn
Setup
git clone https://github.com/YOUR_USERNAME/hn-mcp-server.git
cd hn-mcp-server
npm installCommands
npm run build # Compile TypeScript
npm run dev # Watch mode
npm test # Run all tests
npm run test:watch # Test watch mode
npm run lint # Lint code
npm run format # Format code
npm run check # Lint + type check
npm run ci # Full CI workflowProject Structure
src/
βββ index.ts # Main entry point
βββ server.ts # MCP server initialization
βββ tools/ # MCP tool implementations (one per file)
β βββ search-stories.ts
β βββ get-story.ts
β βββ ...
βββ lib/ # Shared utilities
β βββ hn-client.ts # HN API client
β βββ rate-limiter.ts
β βββ logger.ts
β βββ errors.ts
β βββ validators.ts
βββ types/ # TypeScript type definitions
βββ hn-api.ts
βββ mcp.tsRate Limiting
The HN Algolia API has a limit of 10,000 requests per hour per IP address. This server:
Tracks request count automatically
Warns at 90% (9,000 requests)
Throws error at 95% (9,500 requests)
Resets counter every hour
Logging
Structured JSON logging with correlation IDs:
# Enable debug logging
DEBUG=1 hn-mcp-server
# View logs in Claude Desktop
# macOS: ~/Library/Logs/Claude/mcp*.log
# Windows: %APPDATA%\Claude\logs\mcp*.log
# Linux: ~/.config/claude/logs/mcp*.logError Handling
All errors return MCP-formatted responses with:
Clear error messages
Error codes (RATE_LIMIT_EXCEEDED, ITEM_NOT_FOUND, etc.)
Context for debugging
Suggested user actions
Contributing
Fork the repository
Create a feature branch (
git checkout -b feature/amazing-feature)Make your changes following the constitution principles
Run quality gates (
npm run ci)Commit (
git commit -m 'Add amazing feature')Push (
git push origin feature/amazing-feature)Open a Pull Request
License
MIT License - see LICENSE file for details.
Links
Support
Issues: GitHub Issues
Discussions: GitHub Discussions
Built with β€οΈ following MCP best practices and constitution principles
Available Tools
9 toolsget_ask_hnGet Ask HN PostsB
Retrieve Ask HN posts (questions to the HN community), sorted by date descending.
Inputs: page, hitsPerPage. Returns: hits, nbHits, nbPages
get_front_pageGet Front Page StoriesA
Retrieve stories currently on the Hacker News front page. Returns up to 30 stories.
Inputs: page, hitsPerPage. Returns: hits, nbHits, nbPages
get_latest_storiesGet Latest StoriesB
Retrieve the most recently submitted stories, sorted by date descending.
Inputs: page, hitsPerPage. Returns: hits, nbHits, nbPages
get_show_hnGet Show HN PostsB
Retrieve Show HN posts (projects shared with the HN community), sorted by date descending.
Inputs: page, hitsPerPage. Returns: hits, nbHits, nbPages
get_storyGet StoryA
Retrieve a specific story by ID with full nested comment tree. Returns complete story details including all comments and replies.
Inputs: id (required). Returns: id, author, points, children
get_userGet User ProfileB
Retrieve a user profile by username. Returns karma, account creation date, and bio.
Inputs: username (required). Returns: about, karma, username
search_by_dateSearch by DateB
Search Hacker News content sorted by date (most recent first). Useful for finding latest stories, comments, or posts by specific authors.
Inputs: query (required), tags, numericFilters, page, +1 more. Returns: hits, page, nbHits, nbPages, +1 more
search_commentsSearch CommentsB
Search Hacker News comments by text content. Can filter by author or parent story.
Inputs: query (required), tags, sortByDate, page, +1 more. Returns: hits, nbHits, nbPages
search_storiesSearch StoriesA
Search Hacker News stories by relevance. Returns stories matching the query, sorted by relevance score, points, and comment count.
Inputs: query (required), tags, numericFilters, page, +1 more. Returns: hits, page, nbHits, nbPages, +2 more
Tool Schema Changelog
Recent tool additions, removals, and schema changes observed during successful MCP inspections.
Loading tool schema changelogβ¦
TDQS
Scored across 9 tools
Most tools have distinct purposes, such as get_front_page for front-page stories and get_user for user profiles, but there is some overlap between get_latest_stories and search_by_date, as both retrieve recent content, which could cause confusion. The descriptions help clarify, but the boundaries are not perfectly clear.
All tool names follow a consistent snake_case pattern with a clear verb_noun structure, such as get_front_page and search_stories. This predictability makes it easy for agents to understand and use the tools without ambiguity in naming conventions.
With 9 tools, the server is well-scoped for interacting with Hacker News, covering key actions like retrieving stories, comments, users, and searching. Each tool serves a specific function, and the count is neither too sparse nor overwhelming for the domain.
The tool set provides comprehensive coverage for reading and searching Hacker News content, including stories, comments, and user profiles. A minor gap is the lack of write operations (e.g., posting or voting), but this is reasonable for a read-focused server, and agents can still perform most common tasks effectively.
Related MCP Connectors
Browse Hacker News feeds, threads, and user profiles with full-text search.
Hacker News stories, search and Who is Hiring jobs via the official API. Runs on Apify.
HN front-page, Algolia full-text search, and Show HN launch tracker.
Hacker News MCP β search and retrieve stories from Hacker News
Related MCP Servers
- AlicenseAqualityDmaintenanceEnables AI assistants to search, retrieve, and interact with HackerNews content including stories, comments, polls, and user information. Provides comprehensive access to all HackerNews API endpoints with 15 specialized tools for content discovery and analysis.155MIT
- AlicenseAqualityDmaintenanceEnables AI assistants to access HackerNews content through structured search, front page retrieval, latest posts monitoring, detailed item fetching with comment trees, and user profile viewing via the Algolia API.560 npm7MIT
- FlicenseAqualityDmaintenanceEnables AI assistants to read and search Hacker News for top stories, comments, user profiles, and job listings using the Firebase and Algolia APIs. It facilitates natural language research into community discussions and technological trends across the HN platform.8-
- AlicenseAqualityCmaintenanceProvides AI agents with access to Hacker News data including top stories, story details, comment threads, and full-text search for content research and trend monitoring.5MIT