@missionsquad/mcp-nyt

MCP server interface for the New York Times API (https://api.nytimes.com).

This server exposes NYT API operations for article search, top stories, real-time news, most popular articles, archives, and book best sellers via FastMCP tools.

Features

• FastMCP stdio server (mcp-nyt)
• NYT API key support via hidden tool arg (apiKey) or env fallback (NYT_API_KEY)
• NYT base URL configurable via env (NYT_BASE_URL)
• Strict TypeScript and Zod-validated tool inputs
• Clean, formatted API responses
• Build/test CI and npm publish workflow

Verified API Coverage

• Article Search (search/v2/articlesearch.json)
• Top Stories (topstories/v2/{section}.json)
• Times Wire (news/v3/content/all/all.json)
• Most Popular (mostpopular/v2/{type}/{period}.json)
• Archive (archive/v1/{year}/{month}.json)
• Books (books/v3/lists/current/{list}.json)

Requirements

• Node.js >=20
• Yarn
• NYT API Key (get one at NYT Developer Portal)

Installation

yarn install
yarn build
yarn start

Run as CLI after install/publish:

mcp-nyt

Configuration

Copy .env.example to .env.

| Variable | Required | Default | Description | |---|---|---|---| | NYT_API_KEY | No | unset | NYT API key fallback when hidden apiKey is not passed | | NYT_BASE_URL | No | https://api.nytimes.com/svc | Base URL for NYT API endpoints | | NYT_HTTP_TIMEOUT_MS | No | 30000 | Request timeout in milliseconds |

Hidden Arguments

The following are intentionally not in tool schemas and should be passed as hidden extra args:

• apiKey: NYT API key for request authentication

Resolution order per request:

1. Hidden extra arg
2. Environment fallback (NYT_API_KEY)

If no API key is available, the tool returns a user-facing error.

Tool Surface

Article Search

• nyt_article_search — Search NYT articles by keyword with optional date filtering and sorting.

Top Stories

• nyt_top_stories — Get the current top stories from the New York Times by section.

Times Wire

• nyt_times_wire — Get real-time news feed from the NYT Times Wire service.

Most Popular

• nyt_most_popular — Get the most popular NYT articles by views, shares, or emails over a time period.

Archive

• nyt_archive — Get all NYT article metadata for a given month and year.

Books

• nyt_books — Get the current NYT Best Sellers list by list name.

Response Format

All tool handlers return deterministic JSON text strings. Parse text content on the client side if structured access is needed.

Usage Examples

JSON-RPC tools/call with hidden API key

{
  "method": "tools/call",
  "params": {
    "name": "nyt_article_search",
    "arguments": {
      "query": "artificial intelligence",
      "apiKey": "your-nyt-api-key"
    }
  }
}

FastMCP-style client call

await client.callTool('nyt_top_stories', {
  section: 'technology',
  apiKey: 'your-nyt-api-key',
})

Article Search

await client.callTool('nyt_article_search', {
  query: 'climate change',
  sort: 'newest',
  begin_date: '20250101',
  end_date: '20250401',
  apiKey: 'your-nyt-api-key',
})

Most Popular

await client.callTool('nyt_most_popular', {
  type: 'viewed',
  time_period: '7',
  apiKey: 'your-nyt-api-key',
})

Times Wire

await client.callTool('nyt_times_wire', {
  limit: 10,
  source: 'nyt',
  apiKey: 'your-nyt-api-key',
})

Archive

await client.callTool('nyt_archive', {
  year: 2025,
  month: 3,
  apiKey: 'your-nyt-api-key',
})

Books

await client.callTool('nyt_books', {
  list: 'hardcover-fiction',
  apiKey: 'your-nyt-api-key',
})

Development

Scripts:

• yarn build
• yarn start
• yarn dev
• yarn inspect
• yarn test
• yarn test:coverage

CI/CD

• .github/workflows/build.yaml: build + test on PR open/sync
• .github/workflows/publish.yaml: build + test + publish on main push (markdown-only changes ignored)

License

MIT