![hn-mcp-server](https://socialify.git.ci/wei/hn-mcp-server/image?custom_description=%F0%9F%93%B0+MCP+Server+for+HackerNews+using+Algolia+HackerNews+API&description=1&font=Bitter&language=1&logo=https%3A%2F%2Fraw.githubusercontent.com%2Fhomarr-labs%2Fdashboard-icons%2Frefs%2Fheads%2Fmain%2Fsvg%2Fhacker-news.svg&name=1&owner=1&theme=Light)

[![npm version](https://img.shields.io/npm/v/hn-mcp-server.svg)](https://www.npmjs.com/package/hn-mcp-server)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
[![Node.js Version](https://img.shields.io/badge/node-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
[![MCP](https://img.shields.io/badge/MCP-1.0-purple.svg)](https://modelcontextprotocol.io)

Connect your AI assistant to HackerNews! This [Model Context Protocol](https://modelcontextprotocol.io) server gives Claude, GitHub Copilot, and other AI assistants the ability to search HN, read discussions, and explore user profiles.

## ✨ Features

- 🔍 **Search Posts** - Find stories, comments, and discussions by keyword with advanced filters
- 📰 **Front Page** - Access currently trending posts
- 🆕 **Latest Posts** - Monitor newest content in real-time
- 💬 **Item Details** - Retrieve full posts with nested comment trees
- 👤 **User Profiles** - View author information, karma, and bios

## 🚀 Quick Start

[![Install in VS Code](https://img.shields.io/badge/VS_Code-Install_MCP-0098FF?style=for-the-badge&logo=visualstudiocode&logoColor=ffffff)](https://insiders.vscode.dev/redirect/mcp/install?name=hn-mcp-server&config=%7B%22type%22%3A%22stdio%22%2C%22command%22%3A%22npx%22%2C%22args%22%3A%5B%22-y%20hn-mcp-server%22%5D%7D)
[![Install MCP Server](https://cursor.com/deeplink/mcp-install-dark.svg)](https://cursor.com/en-US/install-mcp?name=hn-mcp-server&config=eyJjb21tYW5kIjoibnB4IC15IGhuLW1jcC1zZXJ2ZXIifQ%3D%3D)

### Other Clients

Add the following MCP server configuration to your client's MCP settings:

```json
{
  "hn-mcp-server": {
    "type": "stdio",
    "command": "npx",
    "args": ["-y", "hn-mcp-server"]
  }
}
```

## 📚 How to Use

Once configured, you can ask your AI assistant natural language questions like:

- *"What are the top stories on HackerNews right now?"*
- *"Search HackerNews for discussions about Rust programming"*
- *"Show me the latest AI-related posts with at least 100 points"*
- *"Get the details and comments for HN item 38456789"*
- *"What's the karma score for user 'pg'?"*

The AI will automatically use the appropriate HackerNews tools to answer your questions.

## 🛠️ Available Tools

### search-posts
Search HackerNews by keyword with filters for content type, points, and date range.

**Example prompts**:
- "Search for stories about TypeScript"
- "Find posts about AI with more than 200 points"
- "Search for comments by author 'dang'"

### get-front-page
Get the current HackerNews front page posts.

**Example prompts**:
- "What's trending on HackerNews?"
- "Show me the HN front page"

### get-latest-posts
Get the most recent posts sorted by date.

**Example prompts**:
- "What are the newest HackerNews stories?"
- "Show me recent Ask HN posts"

### get-item
Retrieve complete item details with nested comments.

**Example prompts**:
- "Get HN item 38456789"
- "Show me the discussion for this story"

### get-user
View user profile information.

**Example prompts**:
- "Tell me about HN user 'pg'"
- "What's the karma for user 'tptacek'?"

## 🔧 Requirements

- **Node.js** 18.0.0 or higher
- **MCP Client** - Any application that supports MCP:
  - [VS Code with GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot)
  - [Cursor](https://cursor.com/)
  - [And many more...](https://modelcontextprotocol.io/clients)

## 🤝 Contributing

Contributions are welcome! Please see [CONTRIBUTING.md](./docs/CONTRIBUTING.md) for details.

## 📖 Documentation

- [API Reference](./docs/API.md) - Detailed API documentation
- [Architecture](./docs/ARCHITECTURE.md) - System design and architecture

## 📄 License

MIT License - See [LICENSE](./LICENSE) for details

## 🔗 Resources

- **npm Package**: https://www.npmjs.com/package/hn-mcp-server
- **GitHub Repository**: https://github.com/wei/hn-mcp-server
- **HackerNews API**: https://hn.algolia.com/api
- **MCP Documentation**: https://modelcontextprotocol.io
- **Report Issues**: https://github.com/wei/hn-mcp-server/issues