Nytimes MCP
FastMCP Server for the NYTimes API
Ask AI about Nytimes MCP
Powered by Claude Β· Grounded in docs
I know everything about Nytimes MCP. Ask me about installation, configuration, usage, or troubleshooting.
0/500
Reviews
Documentation
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.
- Note: if using pip, you should do yourself a favor and do
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 querysort(string, optional): "newest" or "oldest" (default: "newest")begin_date(string, optional): Start date in YYYYMMDD formatend_date(string, optional): End date in YYYYMMDD formatpage(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/sectionsresource for available sections
- See
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-typesresource for available options
- See
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-listsresource for available list names
- See
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_storiesnyt://reference/bestseller-lists- Available bestseller list namesnyt://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
- Fork the repository
- Create your feature branch (
git checkout -b feature/AmazingFeature) - Commit your changes (
git commit -m 'Add some AmazingFeature') - Push to the branch (
git push origin feature/AmazingFeature) - Open a Pull Request
License
MIT License
Security Note
- Never commit your
.envfile - Keep your NYT API key private
- Use environment variables for sensitive data
Contact
Create an issue for bug reports or feature requests.
