hn-mcp-server

v0.5.10 pre-1.0

Browse Hacker News feeds, threads, and user profiles with full-text search via MCP. STDIO or Streamable HTTP.

public 4 tools protocol 2025-11-25 github cyanheads/hn-mcp-server

hn.caseyjhand.com/mcp

claude mcp add --transport http hn-mcp-server https://hn.caseyjhand.com/mcp

codex mcp add hn-mcp-server --url https://hn.caseyjhand.com/mcp

{
  "mcpServers": {
    "hn-mcp-server": {
      "url": "https://hn.caseyjhand.com/mcp"
    }
  }
}

gemini mcp add --transport http hn-mcp-server https://hn.caseyjhand.com/mcp

{
  "mcpServers": {
    "hn-mcp-server": {
      "command": "bunx",
      "args": [
        "mcp-remote",
        "https://hn.caseyjhand.com/mcp"
      ]
    }
  }
}

{
  "mcpServers": {
    "hn-mcp-server": {
      "type": "http",
      "url": "https://hn.caseyjhand.com/mcp"
    }
  }
}

curl -X POST https://hn.caseyjhand.com/mcp \
  -H "Content-Type: application/json" \
  -H "MCP-Protocol-Version: 2025-11-25" \
  -d '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-11-25","capabilities":{},"clientInfo":{"name":"curl","version":"1.0.0"}}}'

Built on@cyanheads/mcp-ts-core v0.10.6

Tools

hn_get_stories

Fetch stories from an HN feed (top, new, best, ask, show, jobs), with title, URL, score, author, and comment count for each story.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hn_get_stories",
    "arguments": {
      "feed": "<feed>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "feed": {
      "type": "string",
      "enum": [
        "top",
        "new",
        "best",
        "ask",
        "show",
        "jobs"
      ],
      "description": "Which HN feed to fetch. \"top\" includes jobs. \"ask\" and \"show\" are Ask HN / Show HN posts."
    },
    "count": {
      "default": 30,
      "description": "Number of stories to return. Larger counts take longer.",
      "type": "number",
      "minimum": 1,
      "maximum": 100
    },
    "offset": {
      "default": 0,
      "description": "Number of stories to skip from the start of the feed. Use with count for pagination.",
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "feed",
    "count",
    "offset"
  ],
  "additionalProperties": false
}

view source ↗

hn_get_thread

Get an item and its comment tree as a threaded discussion, with child comments resolved recursively. Use depth 0 for an item-only lookup.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hn_get_thread",
    "arguments": {
      "itemId": "<itemId>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "itemId": {
      "type": "number",
      "description": "ID of the story, comment, or poll to fetch the thread for."
    },
    "depth": {
      "default": 3,
      "description": "How many levels of replies to resolve. 0 = just the item, no comments. 1 = direct replies only. Popular stories often have more top-level comments than maxComments — to see nesting, raise maxComments together with depth, or call again with a specific comment's itemId to drill into a subtree.",
      "type": "number",
      "minimum": 0,
      "maximum": 10
    },
    "maxComments": {
      "default": 50,
      "description": "Maximum total comments to include across all depth levels. Highest-ranked top-level comments resolve first; replies fill in only after the level above is exhausted.",
      "type": "number",
      "minimum": 1,
      "maximum": 200
    }
  },
  "required": [
    "itemId",
    "depth",
    "maxComments"
  ],
  "additionalProperties": false
}

view source ↗

hn_get_user

Get an HN user profile with karma, about, and optionally their most recent submissions resolved into full items.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hn_get_user",
    "arguments": {
      "username": "<username>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "username": {
      "type": "string",
      "minLength": 1,
      "description": "HN username. Case-sensitive."
    },
    "includeSubmissions": {
      "default": false,
      "description": "Resolve the user's most recent submissions into full items. Without this, only the submission count is available.",
      "type": "boolean"
    },
    "submissionCount": {
      "default": 10,
      "description": "Number of recent submissions to resolve. Only used when includeSubmissions is true.",
      "type": "number",
      "minimum": 1,
      "maximum": 50
    }
  },
  "required": [
    "username",
    "includeSubmissions",
    "submissionCount"
  ],
  "additionalProperties": false
}

view source ↗

hn_search_content

Search Hacker News stories and comments via Algolia. Filterable by content type, author, date range, and minimum points.

read

invocation

{
  "jsonrpc": "2.0",
  "id": 1,
  "method": "tools/call",
  "params": {
    "name": "hn_search_content",
    "arguments": {
      "query": "<query>"
    }
  }
}

schema

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "type": "object",
  "properties": {
    "query": {
      "type": "string",
      "description": "Search terms. Supports simple keywords — Algolia handles stemming and relevance."
    },
    "tags": {
      "description": "Filter results by content type. Omit to search all types.",
      "type": "string",
      "enum": [
        "story",
        "comment",
        "ask_hn",
        "show_hn",
        "front_page"
      ]
    },
    "author": {
      "description": "Filter results to a specific author. Useful for finding a user's posts on a topic (hn_get_user only shows recent submissions).",
      "type": "string"
    },
    "sort": {
      "default": "relevance",
      "description": "Sort order. \"relevance\" for best match, \"date\" for most recent first.",
      "type": "string",
      "enum": [
        "relevance",
        "date"
      ]
    },
    "dateRange": {
      "description": "Filter to a date window. Useful for finding discussions about recent events.",
      "type": "object",
      "properties": {
        "start": {
          "description": "Start date (ISO 8601). Results created after this date.",
          "type": "string"
        },
        "end": {
          "description": "End date (ISO 8601). Results created before this date.",
          "type": "string"
        }
      },
      "additionalProperties": false
    },
    "minPoints": {
      "description": "Minimum score/points. Filters out low-engagement content.",
      "type": "number",
      "minimum": 0
    },
    "count": {
      "default": 30,
      "description": "Number of results to return.",
      "type": "number",
      "minimum": 1,
      "maximum": 50
    },
    "page": {
      "default": 0,
      "description": "Page number for pagination (0-indexed).",
      "type": "number",
      "minimum": 0
    }
  },
  "required": [
    "query",
    "sort",
    "count",
    "page"
  ],
  "additionalProperties": false
}

view source ↗