NewsAPI MCP Server

An MCP (Model Context Protocol) server that provides access to news articles via the NewsAPI. This server allows you to query top headlines, search for articles, and discover news sources through AI assistants like Claude.

Features

This MCP server provides three powerful tools:

1. Get Top Headlines - Retrieve breaking news headlines by country and category
2. List Sources - Discover available news sources by category, language, and country
3. Search Everything - Search through millions of articles with advanced filters

Prerequisites

• Python 3.11 or higher
• A NewsAPI key (Get one here)
• uv package manager (already in use)

Setup

1. Get your NewsAPI key:

   • Visit https://newsapi.org/register
   • Sign up and get your API key
   • Free tier allows 100 requests/day

2. Install dependencies:

   uv sync

3. Set up your environment:

   Option A: Using a .env file (Recommended)

   Create a .env file in the project root:

   # Copy the example file
   cp .env.example .env
   
   # Then edit .env and add your actual API key
   nano .env   # or use your preferred editor

   Or manually create it:

   echo 'NEWS_API_KEY="your-api-key-here"' > .env

   Option B: Using environment variables

   Set the API key as an environment variable:

   export NEWS_API_KEY="your-api-key-here"

   Or add it to your shell configuration file:

   # For zsh (default on macOS)
   echo 'export NEWS_API_KEY="your-api-key-here"' >> ~/.zshrc
   source ~/.zshrc
   
   # For bash
   echo 'export NEWS_API_KEY="your-api-key-here"' >> ~/.bashrc
   source ~/.bashrc

Usage

Testing the Server

To verify the setup works:

# Check syntax
python -m py_compile src/main.py

# If you want to test the server manually, use MCP Inspector:
uv tool run mcpinspect uv run src/main.py

Note: This server is designed to run as an MCP server through Claude Desktop, not as a standalone script.

Connecting from Claude Desktop

Add this configuration to your Claude Desktop MCP settings:

For macOS without load_dotenv():

{
  "mcpServers": {
    "news-api": {
      "command": "uv",
      "args": ["run", "src/main.py"],
      "env": {
        "NEWS_API_KEY": "your-api-key-here"
      }
    }
  }
}

For macOS with load_dotenv():

    "news": {
      "command": "path-to-command/.local/bin/uv",
      "args": [
        "--directory",
        "path-to-folder/src",
        "run",
        "main.py"
      ]
    }

The settings file is typically located at:

• macOS: ~/Library/Application Support/Claude/claude_desktop_config.json

Note: The server uses load_dotenv() to automatically load environment variables from a .env file if present in the project root. If you've set up a .env file, you can omit the "env" section from the configuration above.

Available Tools

1. Get Top Headlines

Get breaking news headlines filtered by country and category.

Required:

• country: 2-letter country code (e.g., "us", "mx", "uk")

Optional:

• category: business, entertainment, general, health, science, sports, technology
• query: Keywords to search for
• page_size: Number of results (1-100, default: 20)
• page: Page number (default: 1)

Example usage in Claude:

Get me the top technology headlines from Mexico

2. List Sources

Discover available news sources by filtering by category, language, and country.

Required:

• category: business, entertainment, general, health, science, sports, technology
• language: Language code (e.g., "en", "es", "de", "fr")
• country: 2-letter country code (e.g., "us", "mx", "uk")

Example usage in Claude:

Show me all Spanish-language technology sources in Mexico

3. Search Everything

Search through millions of articles with advanced filtering options.

Required:

• query: Keywords or phrases to search (supports advanced operators)

Optional:

• search_in: Fields to search (title, description, content) - comma-separated
• sources: Array of source IDs (max 20)
• domains: Array of domains to search
• exclude_domains: Array of domains to exclude
• from_date: Oldest article date (ISO 8601: YYYY-MM-DD)
• to_date: Newest article date (ISO 8601: YYYY-MM-DD)
• language: Language code (en, es, de, etc.)
• sort_by: relevancy, popularity, publishedAt (default: publishedAt)
• page_size: Results per page (1-100, default: 100)
• page: Page number

Advanced search examples:

• Exact phrase: "machine learning"
• Must include: +artificial+intelligence
• Must exclude: -bitcoin
• Boolean: crypto AND (ethereum OR litecoin) NOT bitcoin

Example usage in Claude:

Search for recent articles about AI in technology publications from the last week

Country Codes

Common ISO 3166-1 country codes:

• us - United States
• mx - Mexico
• uk - United Kingdom
• ca - Canada
• de - Germany
• fr - France
• es - Spain
• it - Italy
• jp - Japan
• au - Australia
• br - Brazil

See the NewsAPI documentation for a complete list.

Language Codes

Common ISO 639-1 language codes:

• en - English
• es - Spanish
• de - German
• fr - French
• it - Italian
• pt - Portuguese
• ar - Arabic
• he - Hebrew
• zh - Chinese

Categories

• business - Business news
• entertainment - Entertainment
• general - General news
• health - Health news
• science - Science news
• sports - Sports news
• technology - Technology news

Examples

Example 1: Mexican Politics

What are the top political headlines in Mexico right now?

Example 2: Technology Sector

How is the technology sector doing? Get me the latest tech news from the US.

Example 3: Mexican Sports

Show me the latest sports headlines from Mexico

Example 4: Historical News

What were the top stories about AI from the last month?

Error Handling

The server includes comprehensive error handling:

• Validates API key on startup
• Handles HTTP errors from NewsAPI
• Provides descriptive error messages
• Validates required parameters

Rate Limits

NewsAPI free tier limits:

• 100 requests per day
• 100 requests per 1 minute

For higher limits, consider upgrading at https://newsapi.org/pricing

Project Structure

news/
├── src/
│   ├── main.py        # Main MCP server entry point
│   ├── config.py      # Configuration and validation (uses load_dotenv)
│   ├── api.py         # NewsAPI client functions
│   ├── formatters.py  # Result formatting
│   └── tools.py       # Tool schema definitions
├── .env               # Environment variables (create this file, not in git)
├── .env.example       # Example environment file
├── .gitignore         # Git ignore rules
├── pyproject.toml     # Project dependencies
├── README.md          # This file
└── config.example.json # Example Claude Desktop config

Modular Design:

• src/main.py - Main server and handlers
• src/config.py - Configuration with load_dotenv() support
• src/api.py - API communication
• src/formatters.py - Display formatting
• src/tools.py - Tool schemas

Dependencies

• httpx>=0.28.1 - Async HTTP client
• mcp[cli]>=1.19.0 - Model Context Protocol server
• python-dotenv>=1.2.1 - Load environment variables from .env file

License

This project is for educational use. NewsAPI has its own terms of service.

Support

For issues with the MCP server, check:

• NewsAPI documentation: https://newsapi.org/docs
• NewsAPI status: https://newsapi.org/status

Development

To run the server in development mode:

uv run src/main.py

Or if you prefer:

python src/main.py

Notes

• The server uses python-dotenv to load environment variables from a .env file
• The .env file is automatically ignored by git (via .gitignore)
• The server validates the API key on startup
• Results are formatted for easy reading
• Shows first 10 results with summaries
• All date formats use ISO 8601 standard