HackerNews MCP Server

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

Installation

NPM (when published)

npm install -g hn-mcp-server

From Source

git clone https://github.com/YOUR_USERNAME/hn-mcp-server.git
cd hn-mcp-server
npm install
npm run build
npm link

Quick Start (VS Code)

The fastest way to get started is with VS Code and GitHub Copilot:

1. Clone and build:

   git clone <your-repo-url>
   cd hn-mcp-server
   npm install
   npm run build
   

2. Open in VS Code:

   code .
   

3. Reload VS Code (Ctrl+Shift+P → "Developer: Reload Window")

4. Follow the complete setup checklist: docs/VSCODE_CHECKLIST.md

5. 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:

1. Build the server:

   npm run build
   

2. Configuration is already set up in .vscode/mcp.json:

   {
     "hackernews": {
       "command": "node",
       "args": ["${workspaceFolder}/dist/index.js"],
       "env": {
         "DEBUG": "0"
       }
     }
   }
   

3. Reload VS Code or restart the Copilot extension

4. 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,