HackerNews MCP Server
Provides advanced search capabilities for HackerNews content through Algolia's Search API, enabling keyword search, filtering by author, date, points, and comments, as well as retrieving front page posts and full discussion threads.
Click on "Install 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 Serversearch for recent AI posts with over 200 points"
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
🚀 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
Related MCP server: HackerNews MCP Server
📋 Table of Contents
📦 Installation
Prerequisites
Node.js 22.0.0 or higher
npm 10.0.0 or higher
Install via npm
npm install -g hn-mcp-serverInstall from Source
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server
npm install
npm run build
npm link🚀 Quick Start
With Claude Desktop
Add to your claude_desktop_config.json:
{
"mcpServers": {
"hackernews": {
"command": "npx",
"args": ["-y", "hn-mcp-server"]
}
}
}Config file locations:
macOS:
~/Library/Application Support/Claude/claude_desktop_config.jsonWindows:
%APPDATA%\Claude\claude_desktop_config.jsonLinux:
~/.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:
{
"github.copilot.chat.mcp.servers": {
"hackernews": {
"command": "npx",
"args": ["-y", "hn-mcp-server"]
}
}
}Test Installation
# Verify server starts
hn-mcp-server
# Or via npx
npx hn-mcp-serverThe server will start and wait for MCP client connections via stdio.
💡 Usage Examples
Example 1: Search for AI/ML Posts
Natural Language (in Claude):
Search HackerNews for machine learning articles from the last month with more than 100 pointsExample 2: Browse Front Page
Natural Language:
Show me what's currently on the HackerNews front pageExample 3: Read Discussion
Natural Language:
Get the full discussion for HackerNews post 39381647 including all commentsExample 4: Research a User
Natural Language:
Tell me about the HackerNews user 'pg'Example 5: Advanced Filtering
Natural Language:
Find Show HN posts by user 'todsacerdoti' from 2024 with at least 50 pointsFor more detailed examples, see the Quickstart Guide.
🛠️ Available Tools
search_posts
Search HackerNews posts with advanced filtering options.
Parameters:
query(string, optional) - Search keywordstags(array, optional) - Content type filters:story,comment,poll,show_hn,ask_hn,front_pageauthor(string, optional) - Filter by usernamestoryId(number, optional) - Filter comments by story IDminPoints,maxPoints(number, optional) - Points thresholdsminComments,maxComments(number, optional) - Comment count thresholdsdateAfter,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:
{
"error": "Human-readable error message",
"type": "validation_error | not_found | api_error | rate_limit | unknown",
"details": { "additional": "context" }
}👨💻 Development
Setup
# Clone repository
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server
# Install dependencies
npm install
# Build
npm run buildDevelopment Workflow
# Watch mode (auto-rebuild on changes)
npm run dev
# Run tests
npm test
# Run tests in watch mode
npm run test:watch
# Run tests with coverage
npm run test:coverage
# Lint code
npm run lint
# Fix lint issues
npm run lint:fix
# Format code
npm run format
# Type check without building
npm run typecheckTesting
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.
# Run all tests
npm test
# View coverage report
npm run test:coverage
open coverage/index.html # macOS
start coverage/index.html # WindowsProject Structure
src/
├── index.ts # Main entry point, MCP server setup
├── types/ # TypeScript type definitions
│ ├── hn-api.ts # HackerNews API response types
│ └── mcp-tools.ts # MCP tool schemas
├── tools/ # MCP tool implementations
│ ├── search.ts # search_posts tool
│ ├── front-page.ts # get_front_page tool
│ ├── get-post.ts # get_post tool
│ ├── get-user.ts # get_user tool
│ └── index.ts # Tool registry
├── services/ # Business logic
│ ├── hn-api-client.ts # HackerNews API client
│ └── rate-limiter.ts # Rate limiting
└── lib/ # Utilities
├── validation.ts # Input validation helpers
└── error-handler.ts # Error handling utilities
tests/
├── contract/ # API contract tests
├── integration/ # Tool integration tests
└── unit/ # Unit testsCode 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
anytypes, explicit return types on exported functions
🤝 Contributing
Contributions are welcome! Please follow these guidelines:
Fork the repository
Create a feature branch:
git checkout -b feature/my-featureFollow TDD: Write tests first, then implementation
Ensure tests pass:
npm testEnsure linting passes:
npm run lintMaintain coverage: Keep at 90%+
Commit changes:
git commit -m "Add my feature"Push to branch:
git push origin feature/my-featureOpen a Pull Request
Development Principles
This project follows strict quality standards documented in .specify/memory/constitution.md:
Code Quality First: TypeScript strict mode, no
anytypesTest-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
Available Tools
4 toolsget_front_pageA
Retrieve current HackerNews front page posts. Returns the posts currently featured on the HN front page, ordered by rank. Supports pagination to browse through all front page items. Front page typically contains 30 posts per page (matches the HN website).
| Name | Required | Description | Default |
|---|---|---|---|
| page | No | ||
| hitsPerPage | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden and does well by disclosing key behavioral traits: it's a read operation (implied by 'Retrieve'), supports pagination, specifies the typical page size ('30 posts per page'), and mentions ordering ('ordered by rank'). It doesn't cover rate limits, authentication needs, or error conditions, but provides substantial operational context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is perfectly front-loaded with the core purpose in the first sentence, followed by supporting details about ordering, pagination, and page size. Every sentence adds value with zero wasted words, making it highly efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description provides good coverage of what the tool does, how it behaves, and parameter context. The main gap is the lack of output format details (what fields posts contain, structure of return data), which would be needed for full completeness since there's no output schema.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage for the 2 parameters, the description must compensate. It explains the pagination concept ('Supports pagination to browse through all front page items') and mentions the default page size ('Front page typically contains 30 posts per page'), which helps interpret the 'page' and 'hitsPerPage' parameters. However, it doesn't explicitly map these terms to the parameter names or explain the 'page' numbering starting at 0.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve current HackerNews front page posts'), resource ('HN front page posts'), and distinguishes it from siblings by focusing on the front page rather than individual posts, users, or search results. It provides concrete details about what gets returned ('posts currently featured on the HN front page, ordered by rank').
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides clear context for when to use this tool ('to browse through all front page items') and implies usage through the mention of pagination. However, it doesn't explicitly state when NOT to use it or name alternatives like 'get_post' for individual posts or 'search_posts' for filtered searches, which would be needed for a perfect score.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_postA
Retrieve full details of a specific HackerNews post by its ID. Returns the complete post data including title, URL, author, points, and the entire comment tree with nested replies. Comments are returned in hierarchical structure preserving parent-child relationships. Includes metadata like total comment count and nesting depth.
| Name | Required | Description | Default |
|---|---|---|---|
| postId | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden and does well by disclosing key behavioral traits: it's a read operation (implied by 'Retrieve'), returns hierarchical comment trees with nested replies, and includes metadata like comment count and nesting depth. It doesn't mention rate limits, authentication needs, or error handling, but covers core functionality adequately.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and progressively adding details about returned data and structure. Every sentence earns its place by providing essential information without redundancy, making it efficient and easy to parse.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (1 parameter, no output schema, no annotations), the description is mostly complete. It explains what the tool does, what it returns, and the data structure. However, it lacks details on error cases (e.g., invalid post ID) and doesn't fully compensate for the missing output schema by not specifying exact return fields beyond examples.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It adds meaning by specifying that the parameter is a 'post ID' for HackerNews, implying it's a numeric identifier (though not explicitly stated). This clarifies the parameter's purpose beyond the schema's pattern constraint, but doesn't detail format examples or validation rules.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve full details'), resource ('HackerNews post by its ID'), and scope ('complete post data including title, URL, author, points, and the entire comment tree'). It distinguishes from siblings like get_front_page (list), get_user (user data), and search_posts (search).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'by its ID' and listing returned data, suggesting it's for detailed post inspection rather than browsing or searching. However, it doesn't explicitly state when to use this tool versus alternatives like get_front_page for overview or search_posts for discovery, nor does it mention prerequisites like needing a post ID.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
get_userA
Retrieve HackerNews user profile information by username. Returns user metadata including karma score, account creation date, and about/bio text. Includes computed fields like account age in years and average karma per year to provide context about user activity and reputation.
| Name | Required | Description | Default |
|---|---|---|---|
| username | Yes |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It effectively describes what the tool returns (user metadata, karma score, creation date, bio text, computed fields) and the purpose of those fields ('to provide context about user activity and reputation'). However, it doesn't mention error conditions, rate limits, or authentication requirements.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is efficiently structured in two sentences: the first states the core purpose and parameter, the second details the return data and its value. Every element adds useful information without redundancy or unnecessary elaboration.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a single-parameter read operation with no annotations or output schema, the description provides strong context about what data is returned and why. It covers the tool's purpose, parameter semantics, and return value meaning. The main gap is lack of explicit error handling or rate limit information.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema has 0% description coverage, so the description must compensate. It clearly explains the 'username' parameter's purpose ('by username') and implies constraints through context (HackerNews usernames). While it doesn't specify format details beyond the schema's min/max length, it provides meaningful semantic context for the single parameter.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the specific action ('Retrieve'), resource ('HackerNews user profile information'), and scope ('by username'). It distinguishes this tool from sibling tools like get_front_page, get_post, and search_posts by focusing on user profiles rather than posts or content.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by specifying 'by username' and listing the returned data fields, but it doesn't explicitly state when to use this tool versus alternatives. No guidance is provided about prerequisites, limitations, or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
search_postsA
Search HackerNews posts by keywords with advanced filtering options. Supports filtering by content type (story, comment, poll, etc.), author, date ranges, points thresholds, and comment counts. Returns paginated results with metadata. Default sort is by relevance, but can sort chronologically with sortByDate=true.
| Name | Required | Description | Default |
|---|---|---|---|
| query | No | ||
| tags | No | ||
| author | No | ||
| storyId | No | ||
| minPoints | No | ||
| maxPoints | No | ||
| minComments | No | ||
| maxComments | No | ||
| dateAfter | No | ||
| dateBefore | No | ||
| sortByDate | No | ||
| page | No | ||
| hitsPerPage | No |
TDQS
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It adds useful context such as pagination, default sort behavior, and the ability to sort chronologically, but it lacks details on rate limits, authentication needs, error handling, or what metadata is included in results. This leaves gaps for a tool with 13 parameters.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, starting with the core purpose and then detailing features in a logical flow. Every sentence adds value without redundancy, making it efficient and easy to parse for an AI agent.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the complexity (13 parameters, no annotations, no output schema), the description is moderately complete. It covers the tool's purpose, key parameters, and basic behaviors like pagination and sorting, but lacks details on output format, error cases, or full parameter explanations, which could hinder agent effectiveness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The schema description coverage is 0%, so the description must compensate. It effectively adds meaning by listing key parameters (e.g., content type, author, date ranges, points thresholds, comment counts) and explaining sortByDate and pagination defaults. However, it does not cover all 13 parameters (e.g., storyId is not mentioned), slightly reducing completeness.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with specific verb ('Search') and resource ('HackerNews posts'), distinguishing it from sibling tools like get_front_page (which fetches a specific page) and get_post (which retrieves a single post). It explicitly mentions searching by keywords with advanced filtering, establishing a clear scope.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage context by mentioning 'advanced filtering options' and default behaviors like sorting by relevance, but it does not explicitly state when to use this tool versus alternatives like get_front_page or get_user. No exclusions or specific scenarios are provided, leaving some ambiguity for the agent.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
TDQS
Each tool has a clearly distinct purpose: get_front_page retrieves the front page, get_post fetches a specific post, get_user gets user profiles, and search_posts performs keyword searches. There is no overlap or ambiguity between these functions, making tool selection straightforward for an agent.
All tool names follow a consistent verb_noun pattern (get_front_page, get_post, get_user, search_posts) using snake_case. This uniformity enhances readability and predictability, allowing agents to easily understand the action and target of each tool.
With 4 tools, this server is well-scoped for a HackerNews interface. Each tool serves a distinct and essential function (browsing front page, viewing posts, checking users, and searching), providing a complete yet manageable set without unnecessary complexity or bloat.
The tool set covers core HackerNews interactions effectively: reading posts (front page and specific), user profiles, and searching. A minor gap is the lack of write operations (e.g., posting or commenting), but this is reasonable for a read-only server focused on data retrieval, and agents can still perform most common tasks.
Maintenance
Resources
Unclaimed servers have limited discoverability.
Looking for Admin?
If you are the server author, to access and configure the admin panel.
Related MCP Connectors
Browse Hacker News feeds, threads, and user profiles with full-text search.
Hacker News MCP — search and retrieve stories from Hacker News
Deterministic Hacker News developer sentiment, themes & feature requests via MCP. No API key.
HN front-page, Algolia full-text search, and Show HN launch tracker.
Related MCP Servers
- AlicenseBqualityDmaintenanceAdds powerful Hacker News integration to LLM clients, allowing users to access stories, comments, user profiles, and search functionality through the Model Context Protocol.95819MIT
- 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.5637MIT
- AlicenseAqualityDmaintenanceA service that provides HackerNews content search, retrieval and analysis through the Model Context Protocol, suitable for AI agents and developers.51Apache 2.0
- AlicenseAqualityDmaintenanceProvides programmatic access to Hacker News content via the HN Algolia API. It enables AI assistants to search stories, retrieve comments, access user profiles, and explore the front page in real-time.963MIT
Latest Blog Posts
- Who's Calling? MCP Hosts Are an Identity Blind Spot (And the Spec Knows It)By Om-Shree-0709 on .mcpAgent IdentityOAuth 2.1
- Your AI Chatbot Just Exposed Your CEO's Salary to an InternBy Om-Shree-0709 on .Agent IdentityMCP SecurityOAuth Delegation
- Why MCP Servers Need Execution Sandboxing (And Why Your Current Stack Isn't Enough)By Om-Shree-0709 on .Agentic AiPrompt InjectionWebAssembly
MCP directory API
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/hillaryTse/hn-mcp-server'
If you have feedback or need assistance with the MCP directory API, please join our Discord server