hackernews-mcp-server by void-33 - MCP Server

HackerNews MCP Server

Model Context Protocol server for HackerNews - Search stories, retrieve front page content, access user profiles, and more through the MCP protocol.

Integrate HackerNews into AI assistants like Claude Desktop with natural language queries. Built with TypeScript, the official MCP SDK, and the HackerNews Algolia API.

Features

✨ Full-Text Search - Search HackerNews stories, comments, polls with advanced filtering
🏆 Front Page Access - Get current front page stories as they appear on HN
🆕 Latest Content - Monitor newest stories, comments, and polls in real-time
📖 Item Details - Retrieve complete item information with nested comment threads
👤 User Profiles - Look up user karma, bio, and submission history
⚡ Fast & Reliable - Built on HackerNews Algolia API with 10k requests/hour limit
🔒 Type-Safe - Full TypeScript with Zod validation for inputs and outputs
🧪 Well-Tested - 85%+ test coverage with unit, integration, and E2E tests

Quick Start

Installation

npm install -g @hackernews/mcp-server

Configure with Claude Desktop

Add to your claude_desktop_config.json:

macOS: ~/Library/Application Support/Claude/claude_desktop_config.json
Linux: ~/.config/Claude/claude_desktop_config.json
Windows: %APPDATA%\Claude\claude_desktop_config.json

{
  "mcpServers": {
    "hackernews": {
      "command": "node",
      "args": [
        "/usr/local/lib/node_modules/@hackernews/mcp-server/dist/index.js"
      ]
    }
  }
}

Restart Claude Desktop and start asking about HackerNews!

Full setup guide: See

Usage Examples

Once configured, interact with HackerNews through natural language:

🔍 Search Stories

You: "Find HackerNews stories about Rust from this month with more than 100 points"

The server automatically:

Searches for "Rust" content
Filters to stories only
Applies date and point thresholds
Returns formatted results

📰 Get Front Page

You: "What's trending on HackerNews right now?"

Returns the current front page stories with rankings and metadata.

👥 Look Up Users

You: "Tell me about the HackerNews user 'pg'"

Retrieves user profile with karma, bio, and activity.

💬 Find Comments

You: "Show me recent comments by 'tptacek' about security"

Searches comments by specific author with full-text query.

More examples:

Available Tools

The server exposes 5 MCP tools:

`search`

Full-text search with advanced filtering

Parameters: query, tags, numericFilters, page, hitsPerPage, sortByDate
Use cases: Find stories/comments by topic, author, date range, engagement metrics

`get_front_page`

Retrieve current front page stories

Parameters: page, hitsPerPage
Use cases: Monitor trending content, track front page changes

`get_latest`

Get most recently posted content

Parameters: tags, page, hitsPerPage
Use cases: Real-time monitoring, breaking news, activity feeds

`get_item`

Fetch individual item with full details

Parameters: id
Use cases: Deep-dive into stories, navigate comment threads

`get_user`

Retrieve user profile information

Parameters: username
Use cases: User research, author identification, karma tracking

Full API documentation:

Architecture

Technology Stack

Runtime: Node.js 20.x LTS
Language: TypeScript 5.7.x (strict mode)
MCP SDK: @modelcontextprotocol/sdk (official)
Validation: Zod schemas for type-safe I/O
HTTP Client: Native Node.js fetch API
Testing: Vitest with 85%+ coverage
Linting/Formatting: Biome (unified tooling)

Project Structure

src/
├── index.ts              # Entry point
├── server.ts             # MCP server setup
├── api/                  # HackerNews API client
├── tools/                # MCP tool implementations
└── schemas/              # Zod validation schemas

tests/
├── unit/                 # Fast unit tests
├── integration/          # API integration tests
└── e2e/                  # Full MCP protocol tests

Detailed architecture:

Development

Prerequisites

Node.js 20.x or later
npm or yarn
Git

Setup

# Clone the repository
git clone https://github.com/your-org/hackernews-mcp-server.git
cd hackernews-mcp-server

# Install dependencies
npm install

# Build TypeScript
npm run build

# Run tests
npm test

# Run linting
npm run lint

# Format code
npm run format

Available Scripts

{
  "build": "tsc",
  "test": "vitest run",
  "test:watch": "vitest",
  "test:coverage": "vitest run --coverage",
  "lint": "biome check .",
  "lint:fix": "biome check --write .",
  "format": "biome format --write .",
  "check": "biome check . && tsc --noEmit"
}

Running Locally

# Build the project
npm run build

# Run the server (stdio mode)
node dist/index.js

# Or use tsx for development
npx tsx src/index.ts

Testing Strategy

Unit Tests: Mock API responses, test tool logic in isolation
Integration Tests: Test against real HN API with fixtures
E2E Tests: Full MCP protocol validation via stdio transport
Coverage Target: 85%+ overall, 100% for critical paths

Test documentation:

Contributing

We welcome contributions! Here's how to get started:

Reporting Issues

Bug reports: Create an issue
Feature requests: Create an issue
Questions: Start a discussion

Pull Requests

Fork the repository
Create a branch: git checkout -b feature/your-feature-name
Make changes following our code style
Add tests for new functionality
Run checks: npm run check && npm test
Commit: Follow Conventional Commits
Push and create a pull request

Code Style

TypeScript: Strict mode enabled, explicit types required
Linting/Formatting: Biome (run npm run lint:fix)
Testing: Write tests first (TDD), maintain 85%+ coverage
Documentation: JSDoc for all public APIs
Commits: Conventional Commits format

Development Guidelines

Code Quality: Follow DRY, SOLID principles
Code Reuse: Use existing packages over custom implementations
Error Handling: All error paths explicitly handled
Type Safety: No any types without justification

Full guidelines:

API Reference

HackerNews Algolia API

This server uses the HackerNews Algolia API:

Base URL: https://hn.algolia.com/api/v1
Rate Limit: 10,000 requests/hour per IP
Authentication: None required (public read-only API)

Data Model

Complete TypeScript types and Zod schemas:

Tool Contracts

JSON schemas for all MCP tools:

Troubleshooting

Server not appearing in Claude

Verify claude_desktop_config.json path and syntax
Use absolute path to index.js
Restart Claude Desktop completely
Check Claude's developer console for errors

Rate Limit Errors

HN API: 10,000 requests/hour per IP
Wait for limit to reset (tracked hourly)
Use more specific queries to reduce requests

No Results Found

Simplify search query (fewer filters)
Check spelling (tags/usernames are case-sensitive)
Verify date ranges and numeric filters

Full troubleshooting:

Security

✅ No authentication required (public API)
✅ No data storage (stateless proxy)
✅ No logging of queries or results
✅ Read-only access to HackerNews
✅ Input validation with Zod schemas
✅ Error sanitization (no sensitive data in errors)

Security best practices: All inputs validated, errors sanitized, no external state.

Performance

⚡ Response time: <2s for 95% of queries
📊 Throughput: Up to 1000 requests/hour (configurable)
💾 Memory: <100MB typical usage
🔄 Rate limiting: Respects HN API limits (10k/hour)

Performance tips:

Roadmap

v1.0 (Current)

✅ Core MCP tools (search, front page, latest, item, user)
✅ Full TypeScript implementation
✅ Comprehensive test coverage
✅ Complete documentation

v1.1 (Planned)

Response caching for repeated queries
Batch item retrieval
Search result highlighting
Custom date range helpers

v2.0 (Future)

WebSocket support for real-time updates
Advanced analytics tools
HN Official API integration (submissions, voting)
GraphQL query support

Feature requests: GitHub Issues

FAQ

Q: Do I need a HackerNews account?
A: No, the API is public and doesn't require authentication.

Q: Can I search private or deleted content?
A: No, only publicly visible HN content is accessible.

Q: What's the rate limit?
A: 10,000 requests per hour per IP (HN Algolia API limit).

Q: Can I use this with other MCP clients?
A: Yes! Any MCP-compatible client that supports stdio transport.

Q: Is this an official HackerNews project?
A: No, this is a community project using the public HN API.

Q: How do I report a bug?
A: Create an issue with details and reproduction steps.

License

MIT License - see file for details.

Acknowledgments

HackerNews for the excellent API
Algolia for providing HN search infrastructure
Anthropic for the Model Context Protocol
MCP Community for tools, examples, and support

void-33/hackernews-mcp-server