Skip to main content
Glama
hillaryTse

HackerNews MCP Server

by hillaryTse

HackerNews MCP Server

License: MIT Node Version TypeScript

🚀 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-server

Install 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.json

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

  • Linux: ~/.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-server

The 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 points

Example 2: Browse Front Page

Natural Language:

Show me what's currently on the HackerNews front page

Example 3: Read Discussion

Natural Language:

Get the full discussion for HackerNews post 39381647 including all comments

Example 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 points

For more detailed examples, see the Quickstart Guide.


🛠️ Available Tools

search_posts

Search HackerNews posts with advanced filtering options.

Parameters:

  • query (string, optional) - Search keywords

  • tags (array, optional) - Content type filters: story, comment, poll, show_hn, ask_hn, front_page

  • author (string, optional) - Filter by username

  • storyId (number, optional) - Filter comments by story ID

  • minPoints, maxPoints (number, optional) - Points thresholds

  • minComments, maxComments (number, optional) - Comment count thresholds

  • dateAfter, 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 build

Development 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 typecheck

Testing

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 # Windows

Project 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 tests

Code 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 any types, explicit return types on exported functions


🤝 Contributing

Contributions are welcome! Please follow these guidelines:

  1. Fork the repository

  2. Create a feature branch: git checkout -b feature/my-feature

  3. Follow TDD: Write tests first, then implementation

  4. Ensure tests pass: npm test

  5. Ensure linting passes: npm run lint

  6. Maintain coverage: Keep at 90%+

  7. Commit changes: git commit -m "Add my feature"

  8. Push to branch: git push origin feature/my-feature

  9. Open a Pull Request

Development Principles

This project follows strict quality standards documented in .specify/memory/constitution.md:

  • Code Quality First: TypeScript strict mode, no any types

  • Test-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


📝 License

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


🙏 Acknowledgments


🐛 Support


Built with ❤️ using TypeScript, MCP SDK, and Biome

Available Tools

4 tools
get_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).

ParametersJSON Schema
NameRequiredDescriptionDefault
pageNo
hitsPerPageNo

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
postIdYes

TDQS

A4.4/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines4/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
usernameYes

TDQS

A4.2/5.0
Behavior4/5

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.

Conciseness5/5

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.

Completeness4/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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.

ParametersJSON Schema
NameRequiredDescriptionDefault
queryNo
tagsNo
authorNo
storyIdNo
minPointsNo
maxPointsNo
minCommentsNo
maxCommentsNo
dateAfterNo
dateBeforeNo
sortByDateNo
pageNo
hitsPerPageNo

TDQS

A3.9/5.0
Behavior3/5

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.

Conciseness5/5

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.

Completeness3/5

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.

Parameters4/5

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.

Purpose5/5

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.

Usage Guidelines3/5

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

A4.3/5.0
Disambiguation5/5

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.

Naming Consistency5/5

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.

Tool Count5/5

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.

Completeness4/5

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

ActivityInactive
ResponsivenessNo issues

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

Related MCP Servers

  • A
    license
    A
    quality
    D
    maintenance
    Enables 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.
    5
    63
    7
    MIT
  • A
    license
    A
    quality
    D
    maintenance
    A service that provides HackerNews content search, retrieval and analysis through the Model Context Protocol, suitable for AI agents and developers.
    5
    1
    Apache 2.0

Latest Blog Posts

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