get_bestseller_list
Retrieve New York Times bestseller lists for specific categories like fiction and nonfiction to track popular books.
Instructions
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)
Input Schema
TableJSON Schema
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | hardcover-fiction | |
| offset | No |
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.", }