Skip to main content
Glama
enesjakozh
imprvhub

mcp-claude-hackernews

by imprvhub
OverviewSchemaRelated ServersScoreDiscussions
TypeScript
Hybrid

MCP Claude Hacker News

Trust Score

Features

  • Browse latest stories from Hacker News

  • View top and best-rated stories

  • Get story details

  • Read comments for stories

  • Clean formatting of Hacker News content for better readability

Related MCP server: Claude MCP Server Integration

Demo

Requirements

  • Node.js 16 or higher

  • Claude Desktop

  • Internet connection to access Hacker News API

Installation

Installing Manually

  1. Clone or download this repository:

git clone https://github.com/imprvhub/mcp-claude-hackernews
cd mcp-claude-hackernews

  1. Install dependencies:

npm install

  1. Build the project:

npm run build

Running the MCP Server

There are two ways to run the MCP server:

Option 1: Running manually

  1. Open a terminal or command prompt

  2. Navigate to the project directory

  3. Run the server directly:

node build/index.js

Keep this terminal window open while using Claude Desktop. The server will run until you close the terminal.

Option 2: Auto-starting with Claude Desktop (recommended for regular use)

The Claude Desktop can automatically start the MCP server when needed. To set this up:

Configuration

The Claude Desktop configuration file is located at:

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

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

  • Linux: ~/.config/Claude/claude_desktop_config.json

Edit this file to add the Hacker News MCP configuration. If the file doesn't exist, create it:

{
  "mcpServers": {
    "hackerNews": {
      "command": "node",
      "args": ["ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-hackernews/build/index.js"]
    }
  }
}

Important: Replace ABSOLUTE_PATH_TO_DIRECTORY with the complete absolute path where you installed the MCP

  • macOS/Linux example: /Users/username/mcp-claude-hackernews

  • Windows example: C:\\Users\\username\\mcp-claude-hackernews

If you already have other MCPs configured, simply add the "hackerNews" section inside the "mcpServers" object. Here's an example of a configuration with multiple MCPs:

{
  "mcpServers": {
    "otherMcp1": {
      "command": "...",
      "args": ["..."]
    },
    "otherMcp2": {
      "command": "...",
      "args": ["..."]
    },
    "hackerNews": {
      "command": "node",
      "args": [
        "ABSOLUTE_PATH_TO_DIRECTORY/mcp-claude-hackernews/build/index.js"
      ]
    }
  }
}

The MCP server will automatically start when Claude Desktop needs it, based on the configuration in your claude_desktop_config.json file.

Usage

  1. Restart Claude Desktop after modifying the configuration

  2. In Claude, use the Hacker News tools to interact with Hacker News

  3. The MCP server runs as a child process managed by Claude Desktop

Available Tools

The Hacker News MCP provides 5 specialized tools for different functions:

Tool

Description

Parameters

Example Usage

hn_latest

Get the most recent stories from Hacker News

limit: Optional number of stories (1-50, default: 10)

Get 20 latest stories

hn_top

Get the top-ranked stories from Hacker News

limit: Optional number of stories (1-50, default: 10)

Get 15 top stories

hn_best

Get the best stories from Hacker News

limit: Optional number of stories (1-50, default: 10)

Get 25 best stories

hn_story

Get detailed information about a specific story

story_id: Required story ID (number)

Get story details by ID

hn_comments

Get comments for a story

story_id: Story ID (number) OR story_index: Index from last list (1-based)

Get comments by story ID or index

Tool Parameters Details

hn_latest, hn_top, hn_best

  • limit (optional): Number of stories to fetch

    • Type: Number

    • Range: 1-50

    • Default: 10

hn_story

  • story_id (required): The ID of the story to fetch

    • Type: Number

    • Example: 12345678

hn_comments

  • story_id (optional): The ID of the story to get comments for

    • Type: Number

    • Example: 12345678

  • story_index (optional): The index of the story from the last fetched list

    • Type: Number (1-based)

    • Example: 3 (for the 3rd story in the last list)

Note: For hn_comments, you must provide either story_id OR story_index

Example Usage

Here are various examples of how to use the Hacker News MCP with Claude:

Direct Tool Usage:

"Use hn_latest to get 20 recent stories"
"Use hn_top with limit 15 to get top stories"
"Use hn_best to get 25 best stories"
"Use hn_story with story_id 29384756 to get story details"
"Use hn_comments with story_index 3 to get comments for the 3rd story"
"Use hn_comments with story_id 12345678 to get comments for that story"

Natural Language Queries:

You can also interact with the MCP using natural language. Claude will interpret these requests and use the appropriate tools:

  • "Show me the top 30 stories on Hacker News today"

  • "What are the 40 latest posts on Hacker News?"

  • "I'd like to see the 20 best articles from Hacker News"

  • "Can you fetch me 30 recent tech news stories from Hacker News?"

  • "Tell me what's the top 50 trending topics on Hacker News"

  • "Show me 20 Hacker News stories about machine learning"

  • "Get me the 40 most recent Hacker News headlines"

  • "What are the 30 most active discussions on Hacker News right now?"

  • "I'm interested in reading the 40 most popular Hacker News articles this week"

  • "Show me a list of 20 best programming articles from Hacker News"

  • "Get the comments for story number 5 from the last list"

  • "Show me the details of story ID 12345678"

Language Translation Requests:

You can request Hacker News content to be translated into different languages:

  • "Show me the top 30 stories on Hacker News today in Spanish"

  • "Get the 20 latest Hacker News posts and translate them to French"

  • "I'd like to see the 40 best articles from Hacker News in German"

  • "Show me 30 recent Hacker News stories translated to Japanese"

  • "Get the top 20 Hacker News articles and present them in Portuguese"

Troubleshooting

"Server disconnected" error

If you see the error "MCP Hacker News: Server disconnected" in Claude Desktop:

  1. Verify the server is running:

    • Open a terminal and manually run node build/index.js from the project directory

    • If the server starts successfully, use Claude while keeping this terminal open

  2. Check your configuration:

    • Ensure the absolute path in claude_desktop_config.json is correct for your system

    • Double-check that you've used double backslashes (\\) for Windows paths

    • Verify you're using the complete path from the root of your filesystem

  3. Try the auto-start option:

    • Set up the auto-start script for your operating system as described in the "Setting up auto-start scripts" section

    • This ensures the server is always running when you need it

Tools not appearing in Claude

If the Hacker News tools don't appear in Claude:

  • Make sure you've restarted Claude Desktop after configuration

  • Check the Claude Desktop logs for any MCP communication errors

  • Ensure the MCP server process is running (run it manually to confirm)

  • Verify that the MCP server is correctly registered in the Claude Desktop MCP registry

Checking if the server is running

To check if the server is running:

  • Windows: Open Task Manager, go to the "Details" tab, and look for "node.exe"

  • macOS/Linux: Open Terminal and run ps aux | grep node

If you don't see the server running, start it manually or use the auto-start method.

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the Mozilla Public License 2.0 - see the LICENSE file for details.

Related Links

Available Tools

5 tools
hn_bestB

Get the best stories from Hacker News

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of stories to fetch (1-50, default: 10)

TDQS

B3.4/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations provided. Description only states 'Get' without disclosing read-only nature, side effects, auth, or rate limits. Minimal behavioral 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?

Single sentence, no filler, front-loaded. Every word serves purpose.

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?

Simple tool with one parameter and no output schema. Description is adequate for basic list retrieval, though could mention response format.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema description covers 100% of parameters (limit). Tool description adds no extra meaning beyond schema. Baseline 3 applies.

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 'Get the best stories from Hacker News' uses a specific verb and resource, clearly distinguishing it from sibling tools like hn_comments, hn_latest, and hn_top.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No explicit guidance on when to use or avoid this tool versus siblings. Only implied purpose; lacks context like 'use for curated best stories' vs 'hn_latest for most recent.'

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hn_commentsA

Get comments for a story (by story ID or index from last story list)

ParametersJSON Schema
NameRequiredDescriptionDefault
story_idNoThe ID of the story to get comments for
story_indexNoThe index (1-based) of the story from the last fetched list

TDQS

A4.2/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description bears full burden. It discloses the basic functionality (getting comments) and the two ways to identify the story, but lacks details on pagination, ordering, or rate limits. The behavior is simple enough to be partially transparent.

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 a single concise sentence with no unnecessary words, efficiently conveying the tool's purpose and usage.

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 simple tool with two parameters and no output schema, the description covers the key points: what it does and how to specify the story. It could mention the return format (e.g., list of comments) but is largely complete given the tool's simplicity.

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?

Schema coverage is 100% with descriptions for both parameters. The tool description adds value by explaining that story_index refers to the last fetched list and that either parameter can be used, which is not explicit in the schema.

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 'Get comments for a story' with a specific verb and resource, and distinguishes itself from sibling tools like hn_best or hn_story by focusing on comments. It also specifies two identification methods (story ID or index from last list).

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 tells when to use (to get comments for a story) and how to specify the story. It implies the context (using last fetched list for index) but does not explicitly state when not to use or provide alternatives, though sibling tools cover other story actions.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hn_latestB

Get the latest/newest stories from Hacker News

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of stories to fetch (1-50, default: 10)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, and the description does not disclose behavioral traits such as authentication requirements, rate limits, or any side effects. It only states the action without depth.

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 a single, clear sentence of 8 words, front-loading the core purpose without any redundant or unnecessary text.

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 tool's simplicity and lack of output schema, the description minimally conveys purpose but omits return format or any usage context, making it adequate but not complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The schema covers the sole parameter (limit) with full description, default, and range. The description adds no additional meaning beyond what the schema already provides.

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 specifies the verb 'Get' and resource 'latest/newest stories from Hacker News', clearly distinguishing it from sibling tools like hn_best and hn_top, which imply different sorting.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No guidance is given on when to use this tool versus alternatives like hn_best or hn_top. The description lacks explicit context for selection.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hn_storyA

Get details for a specific story by ID

ParametersJSON Schema
NameRequiredDescriptionDefault
story_idYesThe ID of the story to fetch

TDQS

A3.9/5.0
Behavior3/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

No annotations are provided, so the description is the sole source. It indicates a read operation ('get details'), but does not disclose error behavior, rate limits, or response structure. Basic transparency is achieved.

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 a single, well-structured sentence with no extraneous words or filler. It is optimally concise.

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?

For a simple one-parameter tool with no output schema, the description provides minimal but sufficient context. It lacks detail on what 'details' includes, which is acceptable for a simple fetch.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

Schema coverage is 100% as the only parameter 'story_id' has a description. The description 'by ID' aligns with the parameter, adding no new meaning. Baseline score applies.

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 action ('get details'), the resource ('story'), and the identification method ('by ID'). It distinctly differentiates from sibling tools (lists like hn_best, hn_top) which fetch multiple items.

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 when a specific story ID is known, but does not explicitly exclude cases like fetching stories in bulk or provide alternatives. Sibling tool names indirectly suggest other use cases.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

hn_topB

Get the top-ranked stories from Hacker News

ParametersJSON Schema
NameRequiredDescriptionDefault
limitNoNumber of stories to fetch (1-50, default: 10)

TDQS

B3.3/5.0
Behavior2/5

Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?

The description implies read-only behavior ('Get'), but lacks details about rate limits, authentication, or response structure. With no annotations, the description carries full burden and is insufficient.

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?

A single, clear sentence that is well front-loaded. Every word is necessary; no extraneous information.

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?

For a simple tool with one parameter and no output schema, the description covers the basic action. However, it could mention the return format (e.g., list of story IDs or details) to be fully complete.

Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.

Parameters3/5

Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?

The input schema already describes the 'limit' parameter with range and default (100% coverage). The description adds no new parameter meaning, so baseline 3 is appropriate.

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 action ('Get') and resource ('top-ranked stories from Hacker News'), making the tool's purpose unmistakable. It distinguishes from siblings like 'hn_best' and 'hn_latest' by specifying 'top-ranked'.

Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.

Usage Guidelines2/5

Does the description explain when to use this tool, when not to, or what alternatives exist?

No usage guidance is provided. The description does not indicate when to use this tool over alternatives like 'hn_best' or 'hn_latest', nor does it mention prerequisites or context.

Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.

Install Server
RayrunBuild, deploy, and operate MCP servers without becoming an infrastructure team.ray.runAd

TDQS

A3.8/5.0
Disambiguation3/5

There is ambiguity between hn_best, hn_latest, and hn_top as they all return lists of stories with similar descriptions. The distinction between 'best' and 'top' is not clear. However, hn_story and hn_comments are distinct.

Naming Consistency5/5

All tools follow a consistent 'hn_' prefix followed by a single word, using lowercase snake_case. The pattern is uniform.

Tool Count5/5

Five tools is appropriate for a Hacker News reader, covering story retrieval and comments without being excessive.

Completeness5/5

The tool set covers the main reading operations: fetching story lists (by different rankings), individual story details, and comments. Users can access all major content types, though write operations are absent, which is acceptable for a read-only server.

Maintenance

ActivitySlowing
ResponsivenessSyncing

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

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/imprvhub/mcp-claude-hackernews'

If you have feedback or need assistance with the MCP directory API, please join our Discord server