NYTimes MCP

A FastMCP-based Model Context Protocol (MCP) server that provides access to the New York Times APIs through native MCP tools and resources.

Overview

This MCP server provides 5 specialized tools for accessing various New York Times APIs:

• Article Search - Search the NYT article archive
• News Wire - Real-time news feed
• Most Popular - Most viewed/shared/emailed articles
• Archive - Monthly article archives
• Bestseller Lists - NYT book bestseller lists

Features

• Native MCP Protocol: Built with FastMCP for seamless integration with MCP clients
• 5 Specialized Tools: One tool per NYT API endpoint for maximum flexibility
• 3 Reference Resources: Discoverable resources for available sections, lists, and API limits
• Formatted Responses: Clean, simplified responses for most endpoints
• Type-Safe Parameters: Full type validation on all tool parameters
• Error Handling: Robust error management with detailed error messages

Requirements

• Python 3.13+
• NYT API Key (get one at NYT Developer Portal)
• uv for package management
  • Note: if using pip, you should do yourself a favor and do pip install uv, then feel free to follow the rest of this guide.

Quickest start (Agent MCP settings)

If using Claude Desktop, Claude Code, Gemini CLI, Qwen Code, etc, simply add the following to your MCP settings JSON file, replacing your_api_key_here with your actual NYT API key.

{
  "mcpServers": {
    "nytimes": {
      "command": "uvx",
      "args": [
        "--from",
        "git+https://github.com/jeffmm/nytimes-mcp.git",
        "nytimes-mcp"
      ],
      "env": {
        "NYT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Your agent tool should now be able to access the NYTimes MCP server tools.

Quick Start (manual)

1. Clone and Install

git clone https://github.com/your-username/nytimes-mcp.git
cd nytimes-mcp

2. Install with uv

uv tool install .

3. Configure API Key

Ensure you have your NYT API key in your environment.

export NYT_API_KEY=your_api_key_here

Alternatively, create a .env file:

NYT_API_KEY=your_api_key_here

4. Run the Server

Development Mode (with Inspector)

fastmcp dev src/nytimes_mcp/server.py:mcp

This starts the MCP Inspector UI for testing tools interactively.

Production Mode

uvx nytimes-mcp

Project Structure

nytimes-mcp/
├── src/
│   └── nytimes_mcp/
│       ├── __init__.py
│       ├── server.py         # FastMCP server with tool/resource definitions
│       ├── tools.py           # NYT API tool implementations
│       ├── resources.py       # MCP resource definitions
│       ├── nyt_client.py      # NYT API client logic
│       ├── utils.py           # Response formatting utilities
│       └── config.py          # Configuration settings
├── .env
├── .gitignore
├── pyproject.toml
├── CLAUDE.md
└── README.md

Available MCP Tools

1. search_articles

Search NYT articles by query, date range, and other criteria.

Parameters:

• query (string, required): Search query
• sort (string, optional): "newest" or "oldest" (default: "newest")
• begin_date (string, optional): Start date in YYYYMMDD format
• end_date (string, optional): End date in YYYYMMDD format
• page (int, optional): Page number for pagination

Returns: Formatted response with articles array containing headline, snippet, web_url, and pub_date

2. get_latest_news

Get the latest news items from the NYT news wire.

Parameters:

• limit (int, optional): Number of items to return (default: 20)
• offset (int, optional): Pagination offset (default: 0)
• source (string, optional): "nyt" or "inyt" (default: "nyt")
• section (string, optional): relevant section, e.g. "u.s.", "technology" (default: "all")
  • See nyt://reference/sections resource for available sections

Returns: Formatted response with news_items array

3. get_most_popular

Get the most popular NYT articles.

Parameters:

• type (string, optional): "viewed", "shared", or "emailed" (default: "viewed")
• time_period (string, optional): "1", "7", or "30" days (default: "1")
  • See nyt://reference/popular-types resource for available options

Returns: Formatted response with articles array

4. get_archive

Get NYT articles from a specific month and year archive.

Parameters:

• year (int, optional): Year (default: current year)
• month (int, optional): Month 1-12 (default: current month)

Returns: Full NYT archive API response (unformatted)

5. get_bestseller_list

Get NYT bestseller lists.

Parameters:

• list (string, optional): List name (default: "hardcover-fiction")
  • See nyt://reference/bestseller-lists resource for available list names
• offset (int, optional): Pagination offset (default: 0)

Returns: Full NYT Books API response (unformatted)

Available MCP Resources

Resources provide reference data that can be accessed by MCP clients:

• nyt://reference/sections - Available sections for top_stories
• nyt://reference/bestseller-lists - Available bestseller list names
• nyt://reference/api-limits - NYT API rate limits and usage information

Using with MCP Clients

Claude Desktop (or most other CLI tools)

Add to your MCP configuration JSON:

{
  "mcpServers": {
    "nytimes": {
      "command": "uvx",
      "args": ["nytimes-mcp"],
      "env": {
        "NYT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Or if installed locally

{
  "mcpServers": {
    "nytimes": {
      "command": "uvx",
      "args": ["nytimes-mcp"],
      "env": {
        "NYT_API_KEY": "your_api_key_here"
      }
    }
  }
}

Development

Install Development Dependencies

uv sync

Run Tests

uv run pytest

Development Server with Inspector

uv run fastmcp dev src/nytimes_mcp/server.py:mcp

This opens the MCP Inspector for interactive testing.

API Rate Limits

The NYT API has rate limits (approximately 5 requests/minute, 500 requests/day maximum). Use the nyt://reference/api-limits resource to check current limits.

Contributing

1. Fork the repository
2. Create your feature branch (git checkout -b feature/AmazingFeature)
3. Commit your changes (git commit -m 'Add some AmazingFeature')
4. Push to the branch (git push origin feature/AmazingFeature)
5. Open a Pull Request

License

MIT License

Security Note

• Never commit your .env file
• Keep your NYT API key private
• Use environment variables for sensitive data

Contact

Create an issue for bug reports or feature requests.