GNews API Server

A Model Context Protocol (MCP) server that provides access to the GNews API for fetching news articles and headlines. This server enables AI applications to search for news, get trending headlines, and access comprehensive news data through a standardized interface.

Features

🔧 Tools

• search_news - Search for news articles using keywords with advanced filtering
• get_top_headlines - Get trending news articles by category

📚 Resources

• gnews://supported-languages - List of supported language codes
• gnews://supported-countries - List of supported country codes
• gnews://query-syntax - Comprehensive guide to search query syntax

🎯 Prompts

• create_news_search_prompt - Generate comprehensive news research prompts for specific topics

Installation

1. Clone or download this repository

   git clone <repository-url>
   cd gnews-server
   

2. Install dependencies

   pip install -r requirements.txt
   # or using uv
   uv sync
   

3. Get a GNews API key

   • Visit gnews.io
   • Sign up for a free account
   • Get your API key from the dashboard

4. Set up environment variables

   export GNEWS_API_KEY="your_api_key_here"
   

Usage

Running the Server

Development mode (stdio):

python main.py

Using uv:

uv run main.py

Integration with Claude Desktop

Add to your Claude Desktop configuration file (claude_desktop_config.json):

{
  "mcpServers": {
    "gnews": {
      "command": "python",
      "args": ["/absolute/path/to/gnews-server/main.py"],
      "env": {
        "GNEWS_API_KEY": "your_api_key_here"
      }
    }
  }
}

Integration with Other MCP Clients

The server supports the standard MCP protocol and can be used with any MCP-compatible client. Use the stdio transport for local connections.

API Reference

Tools

search_news

Search for news articles using specific keywords.

Parameters:

• q (required): Search keywords with support for logical operators
• lang (optional): Language code (2 letters, e.g., "en", "es")
• country (optional): Country code (2 letters, e.g., "us", "gb")
• max (optional): Number of articles to return (1-100, default: 10)
• in (optional): Search in specific fields: "title", "description", "content"
• nullable (optional): Allow null values for: "description", "content", "image"
• from (optional): Filter from date (ISO 8601 format)
• to (optional): Filter until date (ISO 8601 format)
• sortby (optional): Sort by "publishedAt" or "relevance"
• page (optional): Page number for pagination

Example queries:

- "Apple iPhone"
- "Apple AND iPhone"
- "Apple OR Microsoft" 
- "(Apple AND iPhone) OR Microsoft"
- "Apple NOT iPhone"
- "Apple iPhone 15" AND NOT "Apple iPhone 14"

Returns:

{
  "success": true,
  "query": "search terms",
  "totalArticles": 150,
  "articles": [
    {
      "title": "Article Title",
      "description": "Article description...",
      "content": "Full article content...",
      "url": "https://example.com/article",
      "image": "https://example.com/image.jpg",
      "publishedAt": "2024-01-01T12:00:00Z",
      "source": {
        "name": "Source Name",
        "url": "https://source.com"
      }
    }
  ],
  "parameters_used": {...}
}

get_top_headlines

Get current trending news articles by category.

Parameters:

• category (optional): News category (default: "general")
  • Available: "general", "world", "nation", "business", "technology", "entertainment", "sports", "science", "health"
• lang (optional): Language code
• country (optional): Country code
• max (optional): Number of articles (1-100, default: 10)
• nullable (optional): Allow null values
• from (optional): Filter from date
• to (optional): Filter until date
• q (optional): Additional search keywords
• page (optional): Page number

Returns: Similar structure to search_news with category-specific trending articles.

Resources

gnews://supported-languages

Returns a formatted list of all supported language codes and names.

gnews://supported-countries

Returns a formatted list of all supported country codes and names.

gnews://query-syntax

Returns comprehensive documentation on search query syntax including logical operators, phrase search, and examples.

Prompts

create_news_search_prompt

Creates a structured prompt for comprehensive news research on a specific topic.

Parameters:

• topic (required): The topic to research
• days_back (optional): Number of days to look back (default: 7)

Advanced Query Syntax

The GNews API supports sophisticated search queries:

Logical Operators

• AND: Apple AND iPhone (both terms must appear)
• OR: Apple OR Microsoft (either term can appear)
• NOT: Apple NOT iPhone (exclude articles with "iPhone")

Phrase Search

• Exact phrases: "Apple iPhone 15" (exact sequence)

Operator Precedence

• OR has higher precedence than AND
• Use parentheses for grouping: (Apple AND iPhone) OR Microsoft

Complex Examples

- Intel AND (i7 OR i9)
- (Windows 7) AND (Windows 10)
- "breaking news" AND NOT "rumor"
- (Tesla OR "electric vehicle") AND NOT "stock price"

Supported Languages

Arabic (ar), Chinese (zh), Dutch (nl), English (en), French (fr), German (de), Greek (el), Hindi (hi), Italian (it), Japanese (ja), Malayalam (ml), Marathi (mr), Norwegian (no), Portuguese (pt), Romanian (ro), Russian (ru), Spanish (es), Swedish (sv), Tamil (ta), Telugu (te), Ukrainian (uk)

Supported Countries

Australia (au), Brazil (br), Canada (ca), China (cn), Egypt (eg), France (fr), Germany (de), Greece (gr), Hong Kong (hk), India (in), Ireland (ie), Italy (it), Japan (jp), Netherlands (nl), Norway (no), Pakistan (pk), Peru (pe), Philippines (ph), Portugal (pt), Romania (ro), Russian Federation (ru), Singapore (sg), Spain (es), Sweden (se), Switzerland (ch), Taiwan (tw), Ukraine (ua), United Kingdom (gb), United States (us)

Error Handling

The server includes comprehensive error handling:

• API Key Validation: Checks for required environment variable
• Parameter Validation: Validates language codes, country codes, and numeric ranges
• Network Error Handling: Graceful handling of connection issues
• API Error Responses: Clear error messages from GNews API

Error responses include:

{
  "success": false,
  "error": "Error description",
  "query": "original query",
  "parameters_used": {...}
}

Rate Limits

GNews API has rate limits based on your subscription plan:

• Free Plan: 100 requests per day
• Paid Plans: Higher limits available

The server will return appropriate error messages if rate limits are exceeded.

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Add tests if applicable
5. Submit a pull request

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

• GNews API Documentation: https://docs.gnews.io/
• MCP Specification: https://modelcontextprotocol.io/
• Issues: Please report bugs and feature requests through the repository's issue tracker

Example Usage in Claude

After setting up the server, you can use it in Claude Desktop:

"Search for recent news about artificial intelligence developments in the last 3 days"

"Get the top technology headlines from the United States"

"Find news articles about climate change, but exclude articles about politics"

"Show me breaking news about electric vehicles from European sources"

The server will automatically use the appropriate tools and provide structured, comprehensive news results.