GNews API MCP 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 
   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,