news-api-mcp-server by hegstadjosh - MCP Server

News API MCP Server

A Model Context Protocol (MCP) server that integrates with the News API to provide real-time news search capabilities for AI assistants like Claude.

Features

Article Search: Search for articles across thousands of news sources using keywords, domains, and date ranges
Top Headlines: Get current breaking news and top stories by country, category, or source
News Sources: Browse available news sources with filtering by category, language, and country
Comprehensive Error Handling: Robust error handling for API limits, network issues, and invalid requests
Human-Readable Formatting: Clean, well-formatted responses optimized for AI consumption
Dedalus Platform Ready: Designed for seamless deployment on the Dedalus platform

Prerequisites

Python 3.12 or higher
News API key (get one free at newsapi.org)

Installation

Local Development

Clone or download this repository
Install dependencies:

pip install -e .

Set your News API key as an environment variable:

export NEWS_API_KEY="your_api_key_here"

Run the server:

python main.py

Docker Deployment

Build the Docker image:

docker build -t news-api-mcp-server .

Run the container:

docker run -e NEWS_API_KEY="your_api_key_here" news-api-mcp-server

Dedalus Platform Deployment

The server is pre-configured for Dedalus deployment with:

main.py entry point in project root
Proper containerization via Dockerfile
Environment variable support for NEWS_API_KEY
Standard MCP server stdio communication

Available Tools

1. search_articles

Search for articles using the News API /v2/everything endpoint.

Parameters:

q (string): Keywords or phrases to search for
sources (string): Comma-separated news source identifiers
domains (string): Comma-separated domains to search
from_date (string): Start date (YYYY-MM-DD format)
to_date (string): End date (YYYY-MM-DD format)
language (string): Language code (e.g., 'en', 'fr')
sort_by (string): Sort by 'relevancy', 'popularity', or 'publishedAt'
page_size (integer): Results per page (1-100, default: 20)
page (integer): Page number (default: 1)

Example Usage:

{
  "name": "search_articles",
  "arguments": {
    "q": "artificial intelligence",
    "language": "en",
    "sort_by": "publishedAt",
    "page_size": 10
  }
}

2. get_top_headlines

Get current top headlines and breaking news using the /v2/top-headlines endpoint.

Parameters:

country (string): 2-letter ISO country code (e.g., 'us', 'gb')
category (string): News category ('business', 'entertainment', 'general', 'health', 'science', 'sports', 'technology')
sources (string): Comma-separated source identifiers
q (string): Keywords to search in headlines
page_size (integer): Results per page (1-100, default: 20)
page (integer): Page number (default: 1)

Example Usage:

{
  "name": "get_top_headlines",
  "arguments": {
    "country": "us",
    "category": "technology",
    "page_size": 5
  }
}

3. get_news_sources

Get available news sources using the /v2/sources endpoint.

Parameters:

category (string): Filter by category
language (string): Filter by language code
country (string): Filter by country code

Example Usage:

{
  "name": "get_news_sources",
  "arguments": {
    "category": "technology",
    "language": "en"
  }
}

Response Format

All tools return human-readable text responses with:

Clear article titles and descriptions
Source attribution and author information
Publication dates in UTC format
Direct URLs for full articles
Structured formatting for easy reading

Error Handling

The server handles various error conditions gracefully:

Invalid API Key: Clear error message with setup instructions
Rate Limiting: Informative message about API limits (100 requests/day for free tier)
Network Issues: Retry suggestions and connectivity troubleshooting
Invalid Parameters: Helpful validation messages for incorrect inputs
API Errors: Detailed error codes and descriptions from News API

Rate Limits

News API free tier limitations:

100 requests per day
15 requests per 15 minutes
Developer tier only (not for production)

The server implements proper error handling for these limits and provides clear feedback when limits are exceeded.

Configuration

Environment Variables

NEWS_API_KEY (required): Your News API key from newsapi.org

News API Endpoints Used

GET /v2/everything - Search all articles
GET /v2/top-headlines - Get breaking news
GET /v2/top-headlines/sources - List news sources

Development

Project Structure

news-api-mcp-server/
├── main.py              # Dedalus entry point
├── pyproject.toml       # Project configuration
├── Dockerfile          # Container setup
├── src/
│   └── news_mcp/
│       ├── __init__.py  # Package initialization
│       ├── server.py    # MCP server implementation
│       └── tools.py     # News API client and tools
└── README.md           # This file

Running Tests

# Install with development dependencies
pip install -e ".[dev]"

# Run tests (when available)
pytest

Contributing

Ensure you have a valid News API key
Test all three tools with various parameters
Verify error handling with invalid inputs
Check formatting of responses for readability

Troubleshooting

Common Issues

"NEWS_API_KEY environment variable is required"
- Set your API key: export NEWS_API_KEY="your_key"
"Invalid API key"
- Verify your key at newsapi.org
- Check for typos in the environment variable
"Rate limit exceeded"
- Free tier: 100 requests/day limit reached
- Wait until next day or upgrade to paid plan
"No articles found"
- Try broader search terms
- Check date ranges (articles older than 1 month may not be available on free tier)
- Verify source names and domains

License

This project is provided as-is for integration with the News API service. Please ensure compliance with News API's terms of service and rate limiting policies.

hegstadjosh/news-api-mcp-server