Hacker News MCP Server

1# Hacker News MCP Server
2 
3A Model Context Protocol (MCP) server that provides tools for fetching stories from Hacker News. This server parses the HTML content from news.ycombinator.com and provides structured data for different types of stories (top, new, ask, show, jobs).
4 
5<a href="https://glama.ai/mcp/servers/oge85xl22f"><img width="380" height="200" src="https://glama.ai/mcp/servers/oge85xl22f/badge" alt="Hacker News MCP server" /></a>
6 
7## Features
8 
9- Fetch different types of stories (top, new, ask, show, jobs)
10- Get structured data including titles, URLs, points, authors, timestamps, and comment counts
11- Configurable limit on number of stories returned
12- Clean error handling and validation
13 
14## Installation
15 
161. Clone the repository:
17```bash
18git clone https://github.com/pskill9/hn-server
19cd hn-server
20```
21 
222. Install dependencies:
23```bash
24npm install
25```
26 
273. Build the server:
28```bash
29npm run build
30```
31 
324. Add to your MCP settings configuration file (location depends on your system):
33 
34For VSCode Claude extension:
35```json
36{
37  "mcpServers": {
38    "hacker-news": {
39      "command": "node",
40      "args": ["/path/to/hn-server/build/index.js"]
41    }
42  }
43}
44```
45 
46## Usage
47 
48The server provides a tool called `get_stories` that can be used to fetch stories from Hacker News.
49 
50### Tool: get_stories
51 
52Parameters:
53- `type` (string): Type of stories to fetch
54  - Options: 'top', 'new', 'ask', 'show', 'jobs'
55  - Default: 'top'
56- `limit` (number): Number of stories to return
57  - Range: 1-30
58  - Default: 10
59 
60Example usage:
61```typescript
62use_mcp_tool with:
63server_name: "hacker-news"
64tool_name: "get_stories"
65arguments: {
66  "type": "top",
67  "limit": 5
68}
69```
70 
71Sample output:
72```json
73[
74  {
75    "title": "Example Story Title",
76    "url": "https://example.com/story",
77    "points": 100,
78    "author": "username",
79    "time": "2024-12-28T00:03:05",
80    "commentCount": 50,
81    "rank": 1
82  },
83  // ... more stories
84]
85```
86 
87## Integrating with Claude
88 
89To use this MCP server with Claude, you'll need to:
90 
911. Have the Claude desktop app or VSCode Claude extension installed
922. Configure the MCP server in your settings
933. Use Claude's natural language interface to interact with Hacker News
94 
95### Configuration
96 
97For the Claude desktop app, add the server configuration to:
98```json
99// ~/Library/Application Support/Claude/claude_desktop_config.json (macOS)
100// %APPDATA%\Claude\claude_desktop_config.json (Windows)
101{
102  "mcpServers": {
103    "hacker-news": {
104      "command": "node",
105      "args": ["/path/to/hn-server/build/index.js"]
106    }
107  }
108}
109```
110 
111For the VSCode Claude extension, add to:
112```json
113// VSCode Settings JSON
114{
115  "mcpServers": {
116    "hacker-news": {
117      "command": "node",
118      "args": ["/path/to/hn-server/build/index.js"]
119    }
120  }
121}
122```
123 
124### Example Interactions
125 
126Once configured, you can interact with Claude using natural language to fetch Hacker News stories. Examples:
127 
128- "Show me the top 5 stories from Hacker News"
129- "What are the latest Ask HN posts?"
130- "Get me the top Show HN submissions from today"
131 
132Claude will automatically use the appropriate parameters to fetch the stories you want.
133 
134![Claude using the Hacker News MCP server](Claude.png)
135 
136### Story Object Structure
137 
138Each story object contains:
139- `title` (string): The story title
140- `url` (string, optional): URL of the story (may be internal HN URL for text posts)
141- `points` (number): Number of upvotes
142- `author` (string): Username of the poster
143- `time` (string): Timestamp of when the story was posted
144- `commentCount` (number): Number of comments
145- `rank` (number): Position in the list
146 
147## Development
148 
149The server is built using:
150- TypeScript
151- Model Context Protocol SDK
152- Axios for HTTP requests
153- Cheerio for HTML parsing
154 
155To modify the server:
156 
1571. Make changes to `src/index.ts`
1582. Rebuild:
159```bash
160npm run build
161```
162 
163## Error Handling
164 
165The server includes robust error handling for:
166- Invalid story types
167- Network failures
168- HTML parsing errors
169- Invalid parameter values
170 
171Errors are returned with appropriate error codes and descriptive messages.
172 
173## Contributing
174 
175Contributions are welcome! Please feel free to submit a Pull Request.
176 
177## License
178 
179MIT License - feel free to use this in your own projects.
180