# HackerNews MCP Server - Quick Start Guide
Get started with the HackerNews MCP Server in 5 minutes.
## Prerequisites
- Node.js 20 LTS or higher
- npm or yarn package manager
- Claude Desktop or any MCP-compatible client
## Installation
### From npm (once published)
```bash
npm install -g hn-mcp-server
```
### From source
```bash
# Clone the repository
git clone https://github.com/YOUR_USERNAME/hn-mcp-server.git
cd hn-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Link globally for testing
npm link
```
## Configuration
### Claude Desktop Setup
1. Open Claude Desktop configuration file:
- macOS: `~/Library/Application Support/Claude/claude_desktop_config.json`
- Windows: `%APPDATA%\Claude\claude_desktop_config.json`
- Linux: `~/.config/claude/claude_desktop_config.json`
2. Add the HackerNews MCP Server to the `mcpServers` section:
```json
{
"mcpServers": {
"hackernews": {
"command": "hn-mcp-server",
"args": []
}
}
}
```
If installed from source, use the full path to the built server:
```json
{
"mcpServers": {
"hackernews": {
"command": "node",
"args": ["/path/to/hn-mcp-server/dist/index.js"]
}
}
}
```
3. Restart Claude Desktop
## Verification
After restarting Claude Desktop, verify the server is running:
1. Start a new conversation
2. Look for the 🔧 (tools) indicator showing available MCP tools
3. You should see 9 HackerNews tools available:
- `search_stories`
- `search_by_date`
- `get_story`
- `get_user`
- `get_front_page`
- `get_latest_stories`
- `get_ask_hn`
- `get_show_hn`
- `search_comments`
## First Tool Call
Try these example queries in Claude Desktop:
### Search Stories
```
Show me the top stories about AI from Hacker News
```
Claude will use the `search_stories` tool internally:
```json
{
"query": "AI",
"tags": "story",
"hitsPerPage": 10
}
```
### Get Front Page
```
What's currently on the Hacker News front page?
```
Claude will use the `get_front_page` tool:
```json
{
"page": 0,
"hitsPerPage": 30
}
```
### Get Story with Comments
```
Show me story 8863 with all its comments
```
Claude will use the `get_story` tool:
```json
{
"id": 8863
}
```
### User Profile
```
Tell me about the Hacker News user 'pg'
```
Claude will use the `get_user` tool:
```json
{
"username": "pg"
}
```
## Common Use Cases
### 1. Research Topics
```
Find recent discussions about TypeScript on Hacker News from the last week
```
### 2. Track Communities
```
Show me the latest Ask HN posts
```
### 3. Follow Authors
```
What has user 'dang' posted recently?
```
### 4. Explore Projects
```
Show me recent Show HN posts about AI tools
```
## Troubleshooting
### Server Not Appearing in Claude
1. Check Claude Desktop logs:
- macOS: `~/Library/Logs/Claude/mcp*.log`
- Windows: `%APPDATA%\Claude\logs\mcp*.log`
- Linux: `~/.config/claude/logs/mcp*.log`
2. Verify the server command works standalone:
```bash
hn-mcp-server
# Should start without errors
```
3. Check the configuration file syntax:
```bash
# Validate JSON
cat ~/.config/claude/claude_desktop_config.json | jq
```
### Rate Limit Errors
The HN Algolia API has a rate limit of 10,000 requests per hour per IP. If you hit the limit:
- Wait for the hourly reset
- Reduce the `hitsPerPage` parameter
- Cache frequently accessed data
### Network Timeouts
If requests timeout:
- Check your internet connection
- Verify HN Algolia API status: https://hn.algolia.com/api
- The server has a 30-second timeout by default
## Next Steps
- Read the [full documentation](./README.md)
- Check the [API reference](./docs/api-reference.md)
- Review [example prompts](./docs/examples.md)
- Contribute: [CONTRIBUTING.md](./CONTRIBUTING.md)
## Support
- Issues: https://github.com/YOUR_USERNAME/hn-mcp-server/issues
- Discussions: https://github.com/YOUR_USERNAME/hn-mcp-server/discussions
- MCP Documentation: https://modelcontextprotocol.io
## License
MIT License - see [LICENSE](./LICENSE) for details
