Hacker News MCP Server

The easiest way to bring real-time Hacker News data and discussion into your LLM, agent, or app workflows.

Instantly turn Hacker News into a programmable, conversational knowledge base for your AI agents and apps!

- Plug-and-play: Instantly connect LLMs, agents, or chatbots to live Hacker News data and discussions.
- Flexible: Use as a local tool, cloud API, or containerized microservice.
- Natural Language Friendly: Users can reference stories by title, keywords, or natural language ("What are people saying about quantum computing?").
- Rich Prompts: Built-in prompt templates for summaries, trending topics, user analysis, and more.
- Production Ready: Robust error handling, health checks, and cloud deployment support out of the box.

- ⚡Multiple Transport Modes: STDIO/MCP and SSE/MCP for flexible LLM/agent integration
- 🌐REST/OpenAPI Endpoints: Direct HTTP access with auto-generated docs
- 📰Full Hacker News Coverage: Access stories, comments, users, trending topics, and more
- 🛡️Robust Error Handling: Clear response models and status codes
- 🧩Easy Configuration: Environment variables for API keys, host, and logging
- 🐳Container Ready: Docker & Docker Compose for painless deployment
- ❤️Health Monitoring: Built-in health check endpoint
- 🔒CORS Support: Secure and configurable origins for web integration

All endpoints are available by default athttp://localhost:8000(or your configured host/port).

- GET /api/stories/top?limit=30— Get top stories
- GET /api/stories/best?limit=30— Get best stories
- GET /api/stories/new?limit=30— Get newest stories
- GET /api/stories/ask?limit=30— Get Ask HN stories
- GET /api/stories/show?limit=30— Get Show HN stories
- GET /api/stories/search?query=YOUR_QUERY&limit=5— Search for stories by title or keywords
- GET /api/stories/by-date?days_ago=1&limit=30— Get stories from N days ago

- GET /api/item/{item_id}— Get a Hacker News item by ID
- GET /api/story/by-title?title=YOUR_TITLE— Get a story (and comments) by title/keywords
- GET /api/story/{story_id}/comments?comment_limit=10— Get a story and its top comments

- GET /api/story/{story_id}/content?format=markdown— Get the actual content from a story's URL
- GET /api/story/content-by-title?title=YOUR_TITLE&format=markdown— Get content by story title

- formatparameter acceptsmarkdown(default) orjson

- GET /api/user/{username}— Get a Hacker News user by username

- GET /api/maxitem— Get the current largest item ID
- GET /api/updates— Get latest item and profile changes
- GET /health— Health check endpoint
- GET /sse-info— Info about the SSE endpoint

- GET /sse— Server-Sent Events (SSE) endpoint for MCP protocol

- GET /docs— Swagger UI (interactive API docs)
- GET /openapi.json— OpenAPI schema (for tool integration)

🗣️ Natural Language & Title-Based Queries

You can search and retrieve stories using natural language or keywords, not just numeric IDs!

- GET /api/stories/search?query=quantum computing— Find stories about quantum computing
- GET /api/story/by-title?title=React framework— Get the latest story and comments about React framework

- "Tell me about that story on quantum computing from yesterday"
- "What's the discussion about the new React framework like?"

These queries are handled via/api/stories/searchand/api/story/by-titleendpoints.

curl "http://localhost:8000/api/stories/search?query=AI+ethics&limit=3"

curl "http://localhost:8000/api/story/by-title?title=OpenAI+GPT-4"

Get the actual content from a story URL (as Markdown):

curl "http://localhost:8000/api/story/12345/content?format=markdown"

curl "http://localhost:8000/api/story/content-by-title?title=quantum+computing&format=markdown"

curl "http://localhost:8000/health"

curl "http://localhost:8000/api/stories/top?limit=5"

See/docsfor full interactive documentation and try endpoints live.

- LLM/AI Agent Developers: Add real-world, up-to-date news and discussion to your agents.
- Chatbot Builders: Power your bots with trending stories and community insights.
- Researchers & Data Scientists: Analyze Hacker News trends, user activity, and topic sentiment.
- Productivity Hackers: Build custom dashboards, notification bots, or research tools.
- Anyone who wants to make Hacker News programmable!

ℹ️Tip:You don't need to know story IDs—just ask for stories by title, topic, or keywords!

# Clone the repository git clone https://github.com/yourusername/hacker-news-mcp.git cd hacker-news-mcp # Install dependencies pip install -r requirements.txt

# Run with SSE transport (default, good for web/remote) python run.py --transport sse --host 127.0.0.1 --port 8000 # Run with STDIO transport (for direct LLM/agent integration) python run.py --transport stdio # Optional: Run with custom log level env LOG_LEVEL=debug python run.py --transport sse

# Build and run with Docker docker build -t hacker-news-mcp . docker run -p 8000:8000 hacker-news-mcp # Or use Docker Compose docker-compose up -d

💡Tip:Works with Claude Desktop, Windsurf, Cursor IDE, and any LLM/agent supporting MCP!

{ "mcpServers": { "hackerNews": { "command": "python", "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"], "env": { "LOG_LEVEL": "info" } } } }

{ "mcpServers": { "hackerNews": { "command": "python", "args": ["/path/to/hacker-news-mcp/run.py", "--transport", "stdio"], "env": { "LOG_LEVEL": "info" } } } }

{ "mcpServers": { "hackerNews": { "url": "https://your-deployed-server.com/sse", "transport": "sse" } } }

- 🔎Basic Data Retrieval

- get_item(id): Get a Hacker News item by ID
- get_user(id): Get a Hacker News user by ID
- get_max_item_id(): Get the current largest item ID

- get_top_stories(limit): Get top stories
- get_best_stories(limit): Get best stories
- get_new_stories(limit): Get newest stories
- get_ask_stories(limit): Get Ask HN stories
- get_show_stories(limit): Get Show HN stories
- get_job_stories(limit): Get job stories

- get_story_content(story_id, format): Get the actual content from a story's URL
- get_story_content_by_title(title, format): Get content by story title
- Format options:"markdown"(default) or"json"

- get_story_with_comments(story_id, comment_limit): Get a story with its comments
- find_stories_by_title(query, limit): Find stories by title or keywords
- get_story_by_title(title): Find and retrieve a story by its title or keywords with comments

- get_updates(): Get latest item and profile changes
- search_by_date(days_ago, limit): Search for stories from approximately N days ago

- 🧑‍💻Item Resources

- hn://item/{id}: Get item by ID
- hn://user/{id}: Get user by ID

- hn://top/{limit}: Get top stories
- hn://best/{limit}: Get best stories
- hn://new/{limit}: Get newest stories
- hn://ask/{limit}: Get Ask HN stories
- hn://show/{limit}: Get Show HN stories
- hn://jobs/{limit}: Get job stories

💡Natural Language Friendly:Users can reference stories by title, keywords, or just ask questions in plain English!

- hn_router(query): Analyzes any HN-related query and routes to the best tools and approach

- hn_story_summary_by_id(story_id): Summarize a Hacker News story by ID
- hn_story_summary_by_title(title): Summarize a story by title/keywords
- hn_story_comment_analysis(title|id): Analyze comments for a story

- hn_story_content_by_id(story_id): Get and analyze the full article content from a story's URL
- hn_story_content_by_title(title): Get and analyze content by searching for a story by title/keywords
- hn_content_filter(story_id, filter_type): Extract specific types of content (technical, code, opinions, etc.)

- hn_advanced_search(query, days, min_score, min_comments): Find stories matching specific criteria
- hn_compare_stories(story_ids): Compare multiple stories to identify similarities and differences
- hn_multi_source_analysis(query, sources_count): Analyze multiple sources on the same topic

- hn_trending_topics(): List current trending topics
- hn_trend_analysis(days, story_type, topic): Analyze trends over time, optionally focused on a specific topic

- hn_user_profile_analysis(username): Analyze a user's activity and interests

- "Summarize that HN story about quantum computing"
- "What's trending on Hacker News today?"
- "Tell me about HN user 'dang'"
- "Give me a detailed analysis of the discussion on AI regulation"

⚡No need for IDs!Just ask naturally—this server matches your request to the right prompt and tools.

"What can you tell me about quantum computing discussions on Hacker News?"

The router analyzes your query, identifies the intent, and recommends the best approach using available tools (e.g., search for quantum computing stories, analyze content, compare perspectives).

"Compare different perspectives on blockchain from Hacker News" "What are the various opinions about the new MacBook Pro?"

Retrieves multiple sources on the same topic, extracts their content, and provides a comprehensive analysis of different viewpoints, areas of agreement/disagreement, and synthesizes insights.

"Show me just the technical parts of HN story 12345" "Extract the code examples from that article about Rust"

Retrieves a story's content and filters it according to specific needs (technical details, code examples, opinions, beginner-friendly explanations, etc.).

"Find popular stories about quantum computing with lots of discussion" "What are the highest-rated AI stories from the past month?"

Performs advanced search with filtering by score, comment count, and timeframe, then analyzes the results.

"How has discussion about AI changed on HN over the last month?" "What topics are gaining traction compared to last week?"

Compares current stories with historical data to identify emerging topics, changing interests, and community engagement patterns.

"Compare HN stories 12345 and 67890" "What's the difference between those two quantum computing articles?"

Compares multiple stories to identify similarities, differences, and relationships between them.

When running with SSE transport, OpenAPI documentation is available at:

- Swagger UI:http://localhost:8000/docs
- ReDoc:http://localhost:8000/redoc
- OpenAPI JSON:http://localhost:8000/openapi.json

- HN_API_KEY: API key for Hacker News (if required in the future)
- LOG_LEVEL: Logging level (debug, info, warning, error, critical)
- FASTMCP_TOOL_ATTEMPT_PARSE_JSON_ARGS: Set to 1 to enable JSON parsing for tool arguments

# Build the Docker image docker build -t gcr.io/your-project-id/hacker-news-mcp . # Push to Google Container Registry docker push gcr.io/your-project-id/hacker-news-mcp

gcloud run deploy hacker-news-mcp \ --image gcr.io/your-project-id/hacker-news-mcp \ --platform managed \ --region us-central1 \ --allow-unauthenticated \ --memory 512Mi \ --set-env-vars="LOG_LEVEL=info"

- Configure MCP Consumers with Cloud Run URL

After deployment, Cloud Run will provide a URL likehttps://hacker-news-mcp-abcdef123-uc.a.run.app. Use this URL in your MCP configuration:

{ "name": "Hacker News", "url": "https://hacker-news-mcp-abcdef123-uc.a.run.app/sse", "transport": "sse" }

# Create a deployment package zip -r deployment.zip . -x ".git" -x ".pytest_cache" -x "__pycache__/*"

- Create a Lambda function in the AWS Console
- Upload the deployment.zip package
- Configure an API Gateway trigger
- Set environment variables as needed
- Configure MCP Consumers with API Gateway URL

Use the API Gateway URL in your MCP configuration:

{ "name": "Hacker News", "url": "https://abcdef123.execute-api.us-east-1.amazonaws.com/prod/sse", "transport": "sse" }

import asyncio from fastmcp import Client from fastmcp.client.transports import SSETransport import json async def main(): # Connect to the server client = Client(SSETransport("http://localhost:8000/sse")) async with client: # List available tools tools = await client.list_tools() print(f"Available tools: {len(tools)}") # Get top stories top_stories = await client.call_tool("get_top_stories", {"limit": 5}) story_ids = json.loads(top_stories[0].text) print(f"Top stories: {story_ids}") # Get a specific story if story_ids: story_result = await client.call_tool("get_item", {"id": story_ids[0]}) story_data = json.loads(story_result[0].text) print(f"Story: {story_data.get('title')}") if __name__ == "__main__": asyncio.run(main())

For LLM agents that support STDIO-based MCP servers:

# Run the server in STDIO mode python run.py --transport stdio

# Run all tests python -m pytest tests/ # Run specific test file python -m pytest tests/test_server.py