NYTimes MCP

Instructions

Implementation Reference

• src/nytimes_mcp/tools.py:199-220 (handler)

  Core handler function implementing the tool logic by making an HTTP request to the NYT Books API endpoint.

  async def get_bestseller_list(list: str = "hardcover-fiction", offset: int = 0) -> dict:
      """
      Get New York Times bestseller lists.
  
      Args:
          list: List name (e.g., "hardcover-fiction", "hardcover-nonfiction", "paperback-nonfiction")
                Default is "hardcover-fiction"
          offset: Pagination offset (default: 0)
  
      Returns:
          Full NYT Books API response (unformatted)
      """
      params = {"offset": offset}
  
      client = get_client()
      response = await client.make_nyt_request(
          f"books/v3/lists/current/{list}.json",
          params,
      )
  
      # Return raw response (no formatting for books)
      return response

• src/nytimes_mcp/server.py:94-108 (registration)

  MCP tool registration with @mcp.tool() decorator. Defines input schema via type hints and delegates execution to the core handler.

  @mcp.tool()
  async def get_bestseller_list(list: str = "hardcover-fiction", offset: int = 0) -> dict:
      """
      Get New York Times bestseller lists.
  
      Args:
          list: List name (e.g., "hardcover-fiction", "hardcover-nonfiction", "paperback-nonfiction")
                Default is "hardcover-fiction". Use the 'nyt://reference/bestseller-lists' resource
                for available list names.
          offset: Pagination offset (default: 0)
  
      Returns:
          Full NYT Books API response (unformatted)
      """
      return await tools.get_bestseller_list(list, offset)

• src/nytimes_mcp/server.py:118-122 (helper)

  MCP resource registration providing reference data for valid 'list' parameter values used by the tool.

  @mcp.resource("nyt://reference/bestseller-lists")
  def list_bestseller_lists() -> dict:
      """Available bestseller list names for the get_bestseller_list tool."""
      return resources.get_bestseller_lists()

• src/nytimes_mcp/resources.py:69-99 (helper)

  Supporting function providing a static list of valid bestseller list names for the tool's input validation and reference.

  def get_bestseller_lists() -> dict:
      """
      Get available bestseller list names for the books endpoint.
  
      Returns:
          Dict with lists array
      """
      return {
          "lists": [
              "combined-print-and-e-book-fiction",
              "combined-print-and-e-book-nonfiction",
              "hardcover-fiction",
              "hardcover-nonfiction",
              "trade-fiction-paperback",
              "paperback-nonfiction",
              "advice-how-to-and-miscellaneous",
              "childrens-middle-grade-hardcover",
              "picture-books",
              "series-books",
              "young-adult-hardcover",
              "audio-fiction",
              "audio-nonfiction",
              "business-books",
              "graphic-books-and-manga",
              "mass-market-monthly",
              "middle-grade-paperback-monthly",
              "young-adult-paperback-monthly",
          ],
          "description": "Available bestseller list names for the get_bestseller_list tool",
          "note": "List names use hyphens instead of spaces. Visit developer.nytimes.com for the complete list.",
      }