Provides access to New York Times APIs including article search, real-time news wire, most popular articles, monthly archives, and bestseller lists through 5 specialized tools.
Click on "Install Server".
Wait a few minutes for the server to deploy. Once ready, it will show a "Started" state.
In the chat, type @ followed by the MCP server name and your instructions, e.g., "@NYTimes MCP search for recent articles about artificial intelligence"
That's it! The server will respond to your query, and you can continue using it as needed.
Here is a step-by-step guide with screenshots.
A FastMCP-based Model Context Protocol (MCP) server that provides access to the New York Times APIs through native MCP tools and resources.
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
Related MCP server: Real Time News Data MCP Server
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
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.
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.
git clone https://github.com/your-username/nytimes-mcp.git
cd nytimes-mcpuv tool install .Ensure you have your NYT API key in your environment.
export NYT_API_KEY=your_api_key_hereAlternatively, create a .env file:
NYT_API_KEY=your_api_key_herefastmcp dev src/nytimes_mcp/server.py:mcpThis starts the MCP Inspector UI for testing tools interactively.
uvx nytimes-mcpnytimes-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.mdSearch 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
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
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
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)
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)
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
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"
}
}
}
}uv syncuv run pytestuv run fastmcp dev src/nytimes_mcp/server.py:mcpThis opens the MCP Inspector for interactive testing.
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.
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
MIT License
Never commit your .env file
Keep your NYT API key private
Use environment variables for sensitive data
Create an issue for bug reports or feature requests.
Get New York Times articles from a specific month and year archive.
Args: year: Year (default: current year) month: Month 1-12 (default: current month)
Returns: Full NYT archive API response (unformatted)
| Name | Required | Description | Default |
|---|---|---|---|
| year | No | ||
| month | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries the full burden of behavioral disclosure. It mentions that the tool returns 'Full NYT archive API response (unformatted)', which hints at the raw, unprocessed nature of the output, but fails to address critical aspects such as rate limits, authentication requirements, error handling, or data format specifics. This leaves significant gaps in understanding the tool's behavior.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is appropriately sized and front-loaded, with the core purpose stated first, followed by parameter details and return information. Each sentence adds value without redundancy. However, minor improvements could include briefer phrasing or bullet points for parameters, but overall it is efficient and well-structured.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no annotations, no output schema), the description is adequate but incomplete. It covers the purpose and parameters well but lacks details on output structure, error cases, and usage context relative to siblings. Without an output schema, more explanation of the 'unformatted' response would enhance completeness, making it minimally viable with clear gaps.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds meaningful semantics beyond the input schema, which has 0% coverage. It explains that 'year' and 'month' parameters are for specifying the archive period, provides default values (current year/month), and clarifies valid ranges (month 1-12). This compensates well for the lack of schema descriptions, though it could detail constraints like year limits or handling of invalid inputs.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get New York Times articles from a specific month and year archive.' It specifies the verb ('Get'), resource ('New York Times articles'), and scope ('from a specific month and year archive'), but does not explicitly differentiate it from sibling tools like 'get_latest_news' or 'search_articles' in terms of when to use each, which prevents a score of 5.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It does not mention sibling tools such as 'get_latest_news' for recent articles or 'search_articles' for keyword-based searches, nor does it specify use cases like historical research versus current news. This lack of comparative context results in minimal guidance for tool selection.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
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)
| Name | Required | Description | Default |
|---|---|---|---|
| list | No | hardcover-fiction | |
| offset | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden. It mentions pagination via 'offset' and references an external resource for list names, but lacks details on rate limits, authentication needs, error handling, or the structure of the 'unformatted' response. For a tool with no annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with a clear purpose statement followed by Args and Returns sections. It uses bullet-like formatting efficiently, though the 'Returns' section could be more descriptive. Every sentence adds value without redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations and no output schema, the description provides basic purpose and parameter info but lacks details on response format, error cases, or operational constraints. It is minimally viable for a simple retrieval tool but incomplete for robust agent use, as it doesn't fully address the complexity implied by external references and pagination.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate. It adds meaningful context for both parameters: 'list' is explained with examples and a reference for available names, and 'offset' is clarified as a pagination offset with default values. This goes beyond the basic schema, though it could detail format constraints more explicitly.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose with a specific verb ('Get') and resource ('New York Times bestseller lists'), distinguishing it from sibling tools like get_archive or get_latest_news. It precisely identifies what data is retrieved without ambiguity.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the type of data retrieved (bestseller lists), but does not explicitly state when to use this tool versus alternatives like get_most_popular or search_articles. No guidance is provided on prerequisites or exclusions, leaving context somewhat open-ended.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the latest news items from the NYT news wire (real-time news feed).
Args: limit: Number of items to return (default: 20) offset: Pagination offset (default: 0) source: News source - "nyt" or "inyt" (default: "nyt") section: News section (default: "all"). e.g. "u.s." or "technology". Use the 'nyt://reference/sections' resource for available section names.
Returns: Formatted response with news_items array containing title, abstract, url, section, subsection, published_date, and byline
| Name | Required | Description | Default |
|---|---|---|---|
| limit | No | ||
| offset | No | ||
| source | No | nyt | |
| section | No | all |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions 'real-time news feed' and describes the return format, which adds some context. However, it lacks details on rate limits, authentication needs, data freshness, or potential errors (e.g., invalid sections). For a tool with no annotations, this is a significant gap in behavioral transparency.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured and appropriately sized. It starts with a clear purpose statement, followed by organized sections for 'Args' and 'Returns' with bullet-like formatting. Each sentence adds value: the purpose sets context, parameter details are essential given low schema coverage, and return format clarifies output. There is no wasted text or redundancy.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given no annotations, 0% schema coverage, and no output schema, the description does a decent job but has gaps. It fully documents parameters and return format, which is crucial. However, it lacks behavioral context (e.g., rate limits, errors) and usage guidelines versus siblings. For a tool with this complexity and lack of structured data, it's adequate but incomplete, meeting minimum viability with clear room for improvement.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
Schema description coverage is 0%, so the description must compensate fully. It provides detailed semantics for all four parameters: 'limit' (number of items, default 20), 'offset' (pagination offset, default 0), 'source' (news source options and default), and 'section' (news section, default, example, and reference for available names). This adds substantial meaning beyond the bare schema, effectively documenting parameter usage and constraints.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the latest news items from the NYT news wire (real-time news feed).' It specifies the verb ('Get'), resource ('latest news items'), and source ('NYT news wire'), making the action and target explicit. However, it doesn't explicitly differentiate from siblings like 'get_most_popular' or 'search_articles', which likely serve different purposes (e.g., popularity-based vs. search-based retrieval).
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives. It mentions a 'real-time news feed' but doesn't clarify how this differs from siblings like 'get_archive' (historical news) or 'get_most_popular' (popular articles). There are no explicit when-to-use or when-not-to-use instructions, leaving the agent to infer usage based on tool names alone.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Get the most popular New York Times articles.
Args: type: Type of popularity - "viewed", "shared", or "emailed" (default: "viewed") time_period: Time period in days - "1", "7", or "30" (default: "1") Use the 'nyt://reference/popular-types' resource for available options.
Returns: Formatted response with articles array containing title, abstract, url, and published_date
| Name | Required | Description | Default |
|---|---|---|---|
| popularity_type | No | viewed | |
| time_period | No | 1 |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
No annotations are provided, so the description carries the full burden of behavioral disclosure. It mentions the return format but doesn't cover important aspects like rate limits, authentication needs, error handling, or whether this is a read-only operation. For a tool with zero annotation coverage, this leaves significant behavioral gaps.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
The description is well-structured with clear sections for Args and Returns, making it easy to parse. It's appropriately sized with no redundant information, though it could be slightly more concise by integrating the resource reference more seamlessly. Every sentence adds value.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
Given the tool's moderate complexity (2 parameters, no output schema, no annotations), the description is partially complete. It covers parameters well and specifies the return format, but lacks behavioral details like error handling or rate limits. Without annotations or output schema, it should do more to be fully comprehensive.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
The description adds substantial meaning beyond the input schema, which has 0% description coverage. It explains the semantics of both parameters: 'type' as popularity type with options and default, and 'time_period' as time period in days with options and default. This fully compensates for the lack of schema descriptions, providing clear parameter context.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool's purpose: 'Get the most popular New York Times articles.' It specifies the resource (NYT articles) and the verb (get), but it doesn't explicitly differentiate from siblings like 'get_latest_news' or 'search_articles' in terms of popularity vs. recency or search criteria. The purpose is clear but lacks sibling differentiation.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description implies usage by specifying the type of popularity and time period, but it doesn't explicitly state when to use this tool versus alternatives like 'get_latest_news' or 'search_articles'. There's no guidance on prerequisites or exclusions, leaving usage context somewhat implied rather than clearly defined.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Search New York Times articles by query, date range, and other criteria.
Args: query: Search query string sort: Sort order - "newest" or "oldest" (default: "newest") begin_date: Start date in YYYYMMDD format (optional) end_date: End date in YYYYMMDD format (optional) page: Page number for pagination, 0-indexed (optional)
Returns: Formatted response with articles array containing headline, snippet, web_url, and pub_date
| Name | Required | Description | Default |
|---|---|---|---|
| query | Yes | ||
| sort | No | best | |
| begin_date | No | ||
| end_date | No | ||
| page | No |
Does the description disclose side effects, auth requirements, rate limits, or destructive behavior?
With no annotations provided, the description carries full burden for behavioral disclosure. It mentions pagination (page parameter) and returns formatted articles, but lacks details on rate limits, authentication needs, result limits, error handling, or whether this is a read-only operation. The description doesn't contradict annotations (none exist), but provides minimal behavioral context.
Agents need to know what a tool does to the world before calling it. Descriptions should go beyond structured annotations to explain consequences.
Is the description appropriately sized, front-loaded, and free of redundancy?
Well-structured with a clear opening sentence followed by Args/Returns sections. Every sentence adds value, though the opening could be slightly more specific about what makes this search unique compared to siblings.
Shorter descriptions cost fewer tokens and are easier for agents to parse. Every sentence should earn its place.
Given the tool's complexity, does the description cover enough for an agent to succeed on first attempt?
For a search tool with 5 parameters, no annotations, and no output schema, the description covers parameters well but lacks behavioral context (rate limits, auth) and doesn't explain the return format beyond listing fields. It's adequate but has clear gaps in completeness.
Complex tools with many parameters or behaviors need more documentation. Simple tools need less. This dimension scales expectations accordingly.
Does the description clarify parameter syntax, constraints, interactions, or defaults beyond what the schema provides?
With 0% schema description coverage, the description fully compensates by documenting all 5 parameters with clear semantics: query purpose, sort options with default, date formats, and pagination details. It adds significant value beyond the bare schema.
Input schemas describe structure but not intent. Descriptions should explain non-obvious parameter relationships and valid value ranges.
Does the description clearly state what the tool does and how it differs from similar tools?
The description clearly states the tool searches New York Times articles with specific criteria (query, date range, etc.), which is a specific verb+resource combination. However, it doesn't explicitly differentiate from sibling tools like 'get_latest_news' or 'get_archive', which might have overlapping functionality.
Agents choose between tools based on descriptions. A clear purpose with a specific verb and resource helps agents select the right tool.
Does the description explain when to use this tool, when not to, or what alternatives exist?
The description provides no guidance on when to use this tool versus alternatives like 'get_latest_news' or 'get_archive'. It mentions search criteria but doesn't specify use cases, exclusions, or comparisons with sibling tools.
Agents often have multiple tools that could apply. Explicit usage guidance like "use X instead of Y when Z" prevents misuse.
Each tool has a clearly distinct purpose targeting different NYT data domains: get_archive retrieves historical articles by month/year, get_bestseller_list fetches book rankings, get_latest_news provides real-time news, get_most_popular shows popular articles, and search_articles enables keyword-based searches. There is no overlap or ambiguity between these functions.
All tools follow a consistent verb_noun naming pattern with 'get_' or 'search_' prefixes: get_archive, get_bestseller_list, get_latest_news, get_most_popular, and search_articles. This uniformity makes the tool set predictable and easy to understand.
With 5 tools, this server is well-scoped for accessing NYT content. Each tool serves a distinct and valuable purpose (archives, bestsellers, news, popularity, and search), and there are no redundant or trivial tools. The count is appropriate for the domain.
The tool set covers major NYT content areas comprehensively, including articles (archive, latest, popular, search) and bestsellers. A minor gap is the lack of tools for specific content types like multimedia, comments, or user interactions, but core reading and discovery workflows are fully supported.
Unclaimed servers have limited discoverability.
If you are the server author, to access and configure the admin panel.
Real-time news search across 500,000+ sources in 60+ languages with sentiment and entities.
News, web search, mail, markets, weather, places, files, calendar, contacts. 67 tools, one endpoint.
Search and analyze global news coverage and US TV transcripts via the GDELT Project APIs.
Search biomedical literature, get article details, find related articles, and explore MeSH terms
We provide all the information about MCP servers via our MCP API.
curl -X GET 'https://glama.ai/api/mcp/v1/servers/jeffmm/nytimes-mcp'
If you have feedback or need assistance with the MCP directory API, please join our Discord server
