# HackerNews MCP Server - Quickstart Guide
**Version**: 1.0.0
**Last Updated**: October 30, 2025
## Overview
The HackerNews MCP Server enables AI agents and developers to interact with HackerNews content through the Model Context Protocol. It provides tools for searching posts, retrieving front page content, accessing detailed post information with comment trees, and fetching user profiles.
**Key Features**:
- 🔍 Advanced search with multiple filters (content type, author, date, points, comments)
- 📰 Front page content retrieval
- 💬 Full comment tree access with nested structure
- 👤 User profile information
- ⚡ Rate limiting (respects 10,000 req/hour HN API limit)
- 🛡️ Type-safe with comprehensive error handling
---
## Installation
### Prerequisites
- Node.js 22.0.0 or higher
- NPM 10.0.0 or higher
### Install via NPM
```bash
npm install -g hn-mcp-server
```
### Install from Source
```bash
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server
npm install
npm run build
npm link
```
---
## Configuration
### Claude Desktop
Add to your `claude_desktop_config.json`:
```json
{
"mcpServers": {
"hackernews": {
"command": "npx",
"args": ["-y", "hn-mcp-server"]
}
}
}
```
**Location**:
- **macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
- **Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
- **Linux**: `~/.config/Claude/claude_desktop_config.json`
### VS Code with GitHub Copilot
Add to your VS Code `settings.json`:
```json
{
"github.copilot.chat.mcp.servers": {
"hackernews": {
"command": "npx",
"args": ["-y", "hn-mcp-server"]
}
}
}
```
### Other MCP Clients
The server uses stdio transport. Configure your MCP client to execute:
```bash
hn-mcp-server
```
---
## Usage Examples
### Example 1: Search for Python Posts
**Natural Language Prompt** (in Claude or Copilot):
```
Search HackerNews for recent Python articles with more than 50 points
```
**Equivalent Tool Call**:
```json
{
"tool": "search_posts",
"arguments": {
"query": "Python",
"tags": ["story"],
"minPoints": 50,
"sortByDate": true,
"hitsPerPage": 10
}
}
```
**Expected Response**:
```json
{
"results": [
{
"objectID": "123456",
"title": "Python 3.13 Released",
"url": "https://example.com/python-3.13",
"author": "python_dev",
"points": 523,
"num_comments": 142,
"created_at": "2025-10-29T10:30:00.000Z"
}
// ... more results
],
"pagination": {
"totalResults": 1847,
"currentPage": 0,
"totalPages": 185,
"resultsPerPage": 10
}
}
```
---
### Example 2: Get Front Page Stories
**Natural Language Prompt**:
```
Show me the current HackerNews front page
```
**Equivalent Tool Call**:
```json
{
"tool": "get_front_page",
"arguments": {
"page": 0,
"hitsPerPage": 30
}
}
```
**Expected Response**: Similar to search results, returns top 30 front page posts with title, URL, points, comments, etc.
---
### Example 3: View Post with Comments
**Natural Language Prompt**:
```
Get the full discussion for HackerNews post 123456 including all comments
```
**Equivalent Tool Call**:
```json
{
"tool": "get_post",
"arguments": {
"postId": "123456"
}
}
```
**Expected Response**:
```json
{
"post": {
"objectID": "123456",
"title": "Ask HN: What are you working on?",
"author": "author_name",
"points": 234,
"num_comments": 156,
"children": [
{
"objectID": "123457",
"author": "commenter1",
"comment_text": "I'm building...",
"children": [
{
"objectID": "123458",
"author": "commenter2",
"comment_text": "That's interesting...",
"children": []
}
]
}
// ... more comments
]
},
"commentCount": 156,
"nestedLevels": 8
}
```
---
### Example 4: Look Up User Profile
**Natural Language Prompt**:
```
Tell me about the HackerNews user 'pg'
```
**Equivalent Tool Call**:
```json
{
"tool": "get_user",
"arguments": {
"username": "pg"
}
}
```
**Expected Response**:
```json
{
"user": {
"username": "pg",
"created_at": "2007-02-19T18:00:00.000Z",
"karma": 155821,
"about": "Founder of Y Combinator..."
},
"accountAgeYears": 18.7,
"avgKarmaPerYear": 8333
}
```
---
### Example 5: Advanced Filtered Search
**Natural Language Prompt**:
```
Find Show HN posts by user 'someuser' from the last 7 days with at least 10 comments
```
**Equivalent Tool Call**:
```json
{
"tool": "search_posts",
"arguments": {
"tags": ["show_hn"],
"author": "someuser",
"dateAfter": "2025-10-23T00:00:00Z",
"minComments": 10,
"sortByDate": true
}
}
```
---
## Tool Reference
### search_posts
**Description**: Search HackerNews posts with advanced filtering
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `query` | string | No | "" | Search keywords |
| `tags` | string[] | No | [] | Content types: story, comment, poll, show_hn, ask_hn, front_page |
| `author` | string | No | - | Filter by username |
| `storyId` | number | No | - | Filter comments by story ID |
| `minPoints` | number | No | - | Minimum points threshold |
| `maxPoints` | number | No | - | Maximum points threshold |
| `minComments` | number | No | - | Minimum comment count |
| `maxComments` | number | No | - | Maximum comment count |
| `dateAfter` | string | No | - | Posts after date (ISO 8601) |
| `dateBefore` | string | No | - | Posts before date (ISO 8601) |
| `sortByDate` | boolean | No | false | Sort chronologically (true) or by relevance (false) |
| `page` | number | No | 0 | Page number (0-indexed) |
| `hitsPerPage` | number | No | 20 | Results per page (1-100) |
---
### get_front_page
**Description**: Retrieve current HackerNews front page
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `page` | number | No | 0 | Page number (0-indexed) |
| `hitsPerPage` | number | No | 30 | Results per page (1-30) |
---
### get_post
**Description**: Get full post details with comment tree
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `postId` | string | Yes | - | HackerNews post ID |
---
### get_user
**Description**: Get user profile information
**Parameters**:
| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| `username` | string | Yes | - | HackerNews username (1-15 chars) |
---
## Error Handling
All tools return structured errors with this format:
```json
{
"error": "Human-readable error message",
"type": "error_category",
"details": {
"additional": "context"
}
}
```
**Error Types**:
- `validation_error`: Invalid input parameters
- `not_found`: Post or user doesn't exist
- `api_error`: HackerNews API failure
- `rate_limit`: Rate limit exceeded (10,000 req/hour)
- `unknown`: Unexpected error
**Example Error**:
```json
{
"error": "User 'nonexistent_user' not found",
"type": "not_found",
"details": {
"username": "nonexistent_user"
}
}
```
---
## Rate Limiting
The server respects HackerNews API's rate limit of **10,000 requests per hour per IP address**.
**Behavior**:
- Tracks requests using token bucket algorithm
- Logs warnings at 80%, 90%, 95% usage
- Returns `rate_limit` error when limit exceeded
- Automatically refills tokens over time
**Best Practices**:
- Cache results when possible
- Use pagination instead of fetching all results
- Be mindful of request frequency in loops
---
## Performance Tips
1. **Use Specific Filters**: Narrow searches with author, date, or point filters to reduce result set size
2. **Limit Results Per Page**: Default 20 results balances detail and performance
3. **Paginate Wisely**: Fetch only pages you need
4. **Cache User Profiles**: User data changes infrequently
5. **Front Page Caching**: Front page updates ~every 10-15 minutes
---
## Troubleshooting
### Server Not Appearing in Claude
1. Verify `claude_desktop_config.json` location and format
2. Restart Claude Desktop completely
3. Check Claude logs: `~/Library/Logs/Claude/` (macOS) or `%APPDATA%\Claude\logs\` (Windows)
### "Command not found" Error
1. Ensure Node.js 22+ is installed: `node --version`
2. Reinstall globally: `npm install -g hn-mcp-server`
3. Try `npx hn-mcp-server` instead
### Rate Limit Errors
1. Wait one hour for rate limit reset
2. Reduce request frequency
3. Implement caching in your application
### Empty Search Results
1. Verify search terms are spelled correctly
2. Try broader query terms
3. Remove overly restrictive filters
4. Check if content type filter matches expected results
---
## Development & Testing
### Run from Source
```bash
# Install dependencies
npm install
# Run in development mode with watch
npm run dev
# Run tests
npm test
# Run tests with coverage
npm run test:coverage
# Lint and format
npm run lint:fix
npm run format
```
### Test with MCP Inspector
```bash
# Install MCP Inspector
npm install -g @modelcontextprotocol/inspector
# Run server with inspector
npx @modelcontextprotocol/inspector hn-mcp-server
```
---
## Support & Resources
- **GitHub**: [github.com/yourusername/hn-mcp-server](https://github.com/yourusername/hn-mcp-server)
- **Issues**: [Report bugs or request features](https://github.com/yourusername/hn-mcp-server/issues)
- **HN API Docs**: [hn.algolia.com/api](https://hn.algolia.com/api)
- **MCP Specification**: [modelcontextprotocol.io](https://modelcontextprotocol.io)
---
## License
MIT License - See [LICENSE](../../../LICENSE) file for details
---
## Next Steps
- Read the full [README](../../../README.md) for detailed documentation
- Explore [data-model.md](./data-model.md) for entity schemas
- Review [contracts/tools.json](./contracts/tools.json) for tool definitions
- Check [research.md](./research.md) for technical decisions
