HN-MCP

HN-MCP is a fast, zero-setup MCP server that lets Claude Desktop and other AI assistants browse Hacker News, search discussions, and analyze tech trends without API keys. It delivers clean data, caching, and JSON-formatted responses tailored for AI assistants.

How to use

you can use HN-MCP from an MCP client to access the following capabilities: browse top stories, search discussions, fetch full story details with comments, analyze a user’s activity, and explain common Hacker News terms. In Claude Desktop or another MCP client, load the HN-MCP server as a local stdio service or run it in HTTP mode if you provide an HTTP endpoint. Once connected, you can ask questions like “What’s trending on Hacker News?” or “Show me discussions about AI.” The MCP server returns structured data that your AI assistant can parse and present clearly.

How to install

Prerequisites: you need Node.js v18 or newer and npm (or yarn). You will also need an MCP-compatible client to connect to the server.

Step-by-step setup using the stdio (local) option with npx:

1) Ensure Node.js is installed
2) Run the MCP server with npm or npx
3) Connect your MCP client to the local stdio endpoint

Step-by-step setup using the HTTP option (API access) is enabled by setting an environment flag when starting the server. Use your MCP client to connect to the returned HTTP endpoint (port 3000 by default).

Common start commands shown in usage examples include the following standard patterns. Use the one that matches your preferred run mode.

# Quick start with npx (stdio mode)
npx hn-mcp

# Quick start for HTTP mode (env var enables HTTP)
HN_MCP_HTTP=true npx hn-mcp

Configuration and usage notes

The server supports both local stdio mode and HTTP mode. For Claude Desktop integration, you commonly configure the client to spawn or connect to the stdio service using the provided command and arguments.

If you choose HTTP mode, you can expose the MCP server on port 3000 by default, and override the port with an environment variable if needed.

Troubleshooting

Common issues you may encounter include command-not-found errors, connection problems, or rate-limiting. Ensure Node.js and npm are installed and try running the server with the full npx path if necessary. If you experience connection problems, verify the server is running and that your MCP client is configured to connect to the correct endpoint. If you hit a rate limit, adjust the client usage or use a cached response where appropriate.

Environment variables you may configure include: HN_MCP_HTTP, HN_MCP_PORT, HN_MCP_NO_CACHE, HN_MCP_RATE_LIMIT. The default HTTP port is 3000, and caching can be disabled with HN_MCP_NO_CACHE.

Development

Developers can build and test locally by installing dependencies, running in development mode, and building the project. The server targets TypeScript with strict typing and uses a caching layer to optimize responses.

Typical steps include installing dependencies, building, and running tests. If you want to run a local deploy script, use the provided helper to start the server on port 3000 or another port as needed.

Available tools

browse_stories

Browse posts from Hacker News by category. Supports top, new, best, ask, show, and job with a limit and returns title, score, author, comments, and URL.

search_hn

Search across Hacker News content with query terms, filters, and sort options using a search API.

get_story_details

Retrieve a story by ID along with its full nested comment threads, with options to limit comments and depth.

user_analysis

Analyze a Hacker News user profile to fetch karma, account age, recent submissions, and activity patterns.

hn_explain

Explain Hacker News terms like karma, Show HN, Ask HN, and related concepts with context.