# HackerNews MCP Server - Quick Start Guide
**Version**: 1.0.0
**Status**: Ready for Implementation
**Date**: October 12, 2025
## What is this?
The HackerNews MCP Server is a [Model Context Protocol](https://modelcontextprotocol.io) server that provides AI assistants and LLMs with structured access to HackerNews content. It exposes 5 powerful tools for searching posts, retrieving front page content, finding latest discussions, fetching detailed items, and viewing user profiles.
### Key Features
✅ **Search Posts** - Find stories, comments, and discussions by keyword
✅ **Front Page** - Get currently trending HackerNews posts
✅ **Latest Posts** - Monitor newest content sorted by date
✅ **Item Details** - Retrieve complete posts with nested comment trees
✅ **User Profiles** - View author information, karma, and bios
---
## Installation
### Prerequisites
- **Node.js**: Version 18.0.0 or higher (for native `fetch` support)
- **npm**: Version 9.0.0 or higher
- **MCP Client**: Claude Desktop, Continue.dev, or any MCP-compatible client
### Install from npm (Coming Soon)
```bash
npm install -g hn-mcp-server
```
### Install from Source
```bash
# Clone the repository
git clone https://github.com/yourusername/hn-mcp-server.git
cd hn-mcp-server
# Install dependencies
npm install
# Build the project
npm run build
# Link globally (optional)
npm link
```
---
## Configuration
### For Claude Desktop
Add to your Claude Desktop configuration file:
**macOS**: `~/Library/Application Support/Claude/claude_desktop_config.json`
**Windows**: `%APPDATA%\Claude\claude_desktop_config.json`
```json
{
"mcpServers": {
"hackernews": {
"command": "node",
"args": ["/path/to/hn-mcp-server/dist/index.js"]
}
}
}
```
Or if installed globally via npm:
```json
{
"mcpServers": {
"hackernews": {
"command": "hn-mcp-server"
}
}
}
```
### For Other MCP Clients
Configure your MCP client to spawn the server process using stdio transport:
```javascript
import { StdioClientTransport } from '@modelcontextprotocol/sdk/client/stdio.js';
const transport = new StdioClientTransport({
command: 'node',
args: ['/path/to/hn-mcp-server/dist/index.js']
});
```
---
## Usage Examples
### Example 1: Search for AI-related stories
**User**: "Search HackerNews for posts about AI with at least 100 points"
**Tool Call**:
```typescript
{
tool: "search-posts",
arguments: {
query: "AI",
tags: ["story"],
numericFilters: ["points>=100"]
}
}
```
**Result**:
```json
{
"hits": [
{
"objectID": "38456789",
"title": "The Rise of AI Agents",
"url": "https://example.com/ai-agents",
"author": "developer",
"points": 342,
"num_comments": 87,
"created_at": "2025-10-12T10:30:00.000Z",
"_tags": ["story"]
}
],
"nbHits": 1542,
"page": 0,
"nbPages": 78
}
```
---
### Example 2: Get current front page
**User**: "What's on the HackerNews front page right now?"
**Tool Call**:
```typescript
{
tool: "get-front-page",
arguments: {
page: 0,
hitsPerPage: 10
}
}
```
**Result**: Returns top 10 front page stories with titles, URLs, points, and comment counts.
---
### Example 3: Find latest Python discussions
**User**: "Show me the most recent comments about Python"
**Tool Call**:
```typescript
{
tool: "get-latest-posts",
arguments: {
tags: ["comment"]
}
}
```
Then use `search-posts` with `query: "Python"` and date sorting.
---
### Example 4: Read a story with all comments
**User**: "Show me the full discussion for HackerNews item 38456789"
**Tool Call**:
```typescript
{
tool: "get-item",
arguments: {
itemId: "38456789"
}
}
```
**Result**: Complete story with nested comment tree (all levels).
---
### Example 5: Check user profile
**User**: "Tell me about the HackerNews user 'pg'"
**Tool Call**:
```typescript
{
tool: "get-user",
arguments: {
username: "pg"
}
}
```
**Result**:
```json
{
"username": "pg",
"karma": 155678,
"about": "Founder of Y Combinator...",
"created": 1160418111
}
```
---
## Available Tools
### 1. search-posts
Search HackerNews by keyword with optional filters.
**Parameters**:
- `query` (required): Search keywords
- `tags` (optional): Filter by type (story, comment, poll, etc.)
- `numericFilters` (optional): Filter by points, date, comments
- `page` (optional): Page number (default: 0)
- `hitsPerPage` (optional): Results per page (default: 20, max: 1000)
**Common Filters**:
- Points: `["points>=100"]`
- Date: `["created_at_i>1728000000"]`
- Comments: `["num_comments>=50"]`
- Combined: `["points>=100", "created_at_i>1728000000"]`
---
### 2. get-front-page
Get current HackerNews front page posts.
**Parameters**:
- `page` (optional): Page number (default: 0)
- `hitsPerPage` (optional): Results per page (default: 30, max: 1000)
**Notes**:
- Automatically filters for front_page items
- Sorted by HackerNews ranking algorithm
- Typically 30 items on page 0
---
### 3. get-latest-posts
Get most recent posts sorted by date.
**Parameters**:
- `tags` (optional): Filter by type (story, comment, etc.)
- `page` (optional): Page number (default: 0)
- `hitsPerPage` (optional): Results per page (default: 20, max: 1000)
**Use Cases**:
- Monitor new submissions: `tags: ["story"]`
- Track new comments: `tags: ["comment"]`
- See all new activity: (no tags)
---
### 4. get-item
Retrieve complete item details with nested comments.
**Parameters**:
- `itemId` (required): HackerNews item ID (e.g., "38456789")
**Returns**:
- Full item metadata
- Complete nested comment tree (all levels)
- Processing time increases with comment depth
**Notes**:
- No depth limit on comments
- Deleted items may return error
- Large threads (>500 comments) may take 2-3 seconds
---
### 5. get-user
Get user profile information.
**Parameters**:
- `username` (required): HackerNews username (alphanumeric + underscore)
**Returns**:
- Username
- Karma score
- Bio/about text (may contain HTML)
- Account creation date (Unix timestamp)
**Notes**:
- Username is case-sensitive
- Non-existent users return error
- Public profiles only (no private data)
---
## Advanced Usage
### Pagination
All search tools support pagination:
```typescript
// First page
{ query: "Python", page: 0, hitsPerPage: 20 }
// Second page
{ query: "Python", page: 1, hitsPerPage: 20 }
// Custom page size
{ query: "Python", page: 0, hitsPerPage: 50 }
```
**Important**: Pages are 0-indexed (first page is 0, not 1).
---
### Complex Searches
Combine multiple filters for precise results:
```typescript
{
query: "machine learning",
tags: ["story", "front_page"],
numericFilters: [
"points>=100",
"created_at_i>1728000000",
"num_comments>=20"
],
page: 0,
hitsPerPage: 50
}
```
This finds:
- Stories about "machine learning"
- Currently on front page
- At least 100 points
- Posted after October 2025
- At least 20 comments
- First 50 results
---
### Date Filtering
Unix timestamps for recent dates:
| Date | Timestamp | Filter |
|------|-----------|--------|
| October 1, 2025 | 1727740800 | `created_at_i>1727740800` |
| Last 24 hours | `Date.now()/1000 - 86400` | `created_at_i>${timestamp}` |
| Last week | `Date.now()/1000 - 604800` | `created_at_i>${timestamp}` |
JavaScript example:
```javascript
const oneDayAgo = Math.floor(Date.now() / 1000) - 86400;
const filter = `created_at_i>${oneDayAgo}`;
```
---
### Author Filtering
Search posts by specific author:
```typescript
{
query: "", // Empty query for all posts
tags: ["author_pg"], // Posts by user 'pg'
numericFilters: []
}
```
Or search author's content by keyword:
```typescript
{
query: "startup",
tags: ["author_pg"],
numericFilters: []
}
```
---
## Error Handling
### Common Errors
**Validation Error**:
```json
{
"type": "validation",
"message": "Validation error: query must contain at least 1 character"
}
```
**Not Found**:
```json
{
"type": "not_found",
"message": "Item not found: No item with ID '999999'"
}
```
**Rate Limit**:
```json
{
"type": "rate_limit",
"message": "Rate limit exceeded: 10,000 requests per hour maximum",
"statusCode": 429
}
```
**API Error**:
```json
{
"type": "api",
"message": "API error: Failed to fetch from HackerNews API",
"statusCode": 500
}
```
---
## Performance Tips
### Response Times
| Operation | Expected Time | Notes |
|-----------|---------------|-------|
| Search queries | < 2 seconds | Depends on complexity |
| Front page | < 1 second | Simple query |
| Latest posts | < 1 second | Simple query |
| Item retrieval | < 3 seconds | Increases with comments |
| User profile | < 1 second | Simple lookup |
### Optimization Strategies
1. **Pagination**: Use smaller `hitsPerPage` for faster responses
2. **Specific Tags**: Filter by type to reduce result set
3. **Numeric Filters**: Pre-filter data at API level
4. **Item Retrieval**: Be patient with large comment threads (>500 comments)
---
## Rate Limits
**HackerNews API Limit**: 10,000 requests per hour per IP address
**Strategies**:
- **Cache Results**: Store frequently accessed data locally
- **Batch Requests**: Combine searches when possible
- **Monitor Usage**: Track request counts
- **Retry Logic**: Wait before retrying on 429 errors
**When Rate Limited**:
1. Error message indicates rate limit exceeded
2. Wait at least 1 minute before retrying
3. Consider reducing request frequency
4. Implement exponential backoff
---
## Troubleshooting
### Server won't start
**Check**:
- Node.js version >= 18.0.0: `node --version`
- Dependencies installed: `npm install`
- Built correctly: `npm run build`
- Path in config is correct
### No tools showing in client
**Check**:
- MCP client configuration is correct
- Server process is running (check logs)
- Restart MCP client after config change
- Check client's MCP server logs for errors
### Validation errors
**Check**:
- Query is not empty for search-posts
- Page numbers are non-negative
- hitsPerPage is between 1 and 1000
- Username is alphanumeric + underscore
- itemId is not empty
### Slow responses
**Check**:
- Network connection to hn.algolia.com
- Request complexity (large comment threads)
- HackerNews API status
- Consider reducing hitsPerPage
---
## Development
### Running Tests
```bash
# Run all tests
npm test
# Run with coverage
npm run test:coverage
# Run specific test suite
npm test -- search-posts
# Watch mode
npm test -- --watch
```
### Linting & Formatting
```bash
# Check code quality
npm run lint
# Format code
npm run format
# Check formatting without changes
npm run format:check
```
### Building
```bash
# Build for production
npm run build
# Build and watch for changes
npm run build:watch
# Clean build directory
npm run clean
```
---
## Examples Gallery
### Example 1: Daily AI News Digest
Search for today's AI stories with high engagement:
```typescript
const oneDayAgo = Math.floor(Date.now() / 1000) - 86400;
{
tool: "search-posts",
arguments: {
query: "AI OR artificial intelligence",
tags: ["story"],
numericFilters: [
`created_at_i>${oneDayAgo}`,
"points>=50"
],
hitsPerPage: 20
}
}
```
---
### Example 2: Track Show HN Projects
Find recent Show HN posts:
```typescript
{
tool: "search-posts",
arguments: {
query: "",
tags: ["show_hn"],
page: 0,
hitsPerPage: 30
}
}
```
---
### Example 3: Analyze User Activity
Get user profile then search their posts:
```typescript
// Step 1: Get user info
{
tool: "get-user",
arguments: {
username: "tptacek"
}
}
// Step 2: Search their posts
{
tool: "search-posts",
arguments: {
query: "",
tags: ["author_tptacek"],
hitsPerPage: 50
}
}
```
---
### Example 4: Monitor Specific Discussion
Get item and all comments, then check for updates periodically:
```typescript
{
tool: "get-item",
arguments: {
itemId: "38456789"
}
}
// Later, search for new comments on this story:
{
tool: "search-posts",
arguments: {
query: "",
tags: ["comment", "story_38456789"],
hitsPerPage: 100
}
}
```
---
## FAQ
**Q: Is this server rate-limited?**
A: The server respects HackerNews API limits (10,000 req/hour). The server itself has no additional rate limiting.
**Q: Can I search for multiple keywords?**
A: Yes! Use boolean operators: `"Python OR JavaScript"`, `"AI AND startup"`
**Q: How far back does search history go?**
A: The HackerNews API indexes all content since the beginning of HackerNews (2007).
**Q: Can I post comments or vote?**
A: No. This server is read-only. It only retrieves data, never modifies it.
**Q: What about deleted or dead posts?**
A: Deleted posts may return errors or null. Dead/flagged posts are marked in the API response but still accessible.
**Q: How do I get items from a specific date?**
A: Use `created_at_i` numeric filters with Unix timestamps. See "Date Filtering" section above.
**Q: Can I search by multiple tags?**
A: Yes! Use an array: `tags: ["story", "show_hn"]` (AND logic) or `tags: ["(story,comment)"]` (OR logic with parentheses).
**Q: Why are some fields null?**
A: Different item types have different fields. Comments don't have titles/URLs, stories don't have parent_ids, etc.
---
## Next Steps
1. **Configure** your MCP client with the server
2. **Test** basic queries to verify it works
3. **Explore** different search patterns and filters
4. **Build** your own workflows and use cases
5. **Contribute** improvements or report issues on GitHub
---
## Resources
- **HackerNews API Docs**: https://hn.algolia.com/api
- **MCP Documentation**: https://modelcontextprotocol.io
- **GitHub Repository**: https://github.com/yourusername/hn-mcp-server
- **Report Issues**: https://github.com/yourusername/hn-mcp-server/issues
---
## License
MIT License - See LICENSE file for details
---
## Support
- **Issues**: GitHub Issues
- **Discussions**: GitHub Discussions
- **Email**: support@example.com (if applicable)
**Happy Hacking! 🚀**