# 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](https://developer.nytimes.com/))
- 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.

```json
{
  "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

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

### 2. Install with uv

```bash
uv tool install .
```

### 3. Configure API Key

Ensure you have your NYT API key in your environment.

```bash
export NYT_API_KEY=your_api_key_here
```

Alternatively, create a `.env` file:

```env
NYT_API_KEY=your_api_key_here
```

### 4. Run the Server

#### Development Mode (with Inspector)

```bash
fastmcp dev src/nytimes_mcp/server.py:mcp
```

This starts the MCP Inspector UI for testing tools interactively.

#### Production Mode

```bash
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:

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

Or if installed locally

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

## Development

### Install Development Dependencies

```bash
uv sync
```

### Run Tests

```bash
uv run pytest
```

### Development Server with Inspector

```bash
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.