🛠️ Robust Error Handling

Comprehensive error handling for API failures and invalid inputs, with helpful error messages.

🌍 Language Support

Automatic fallback to English for unsupported language codes with appropriate user notifications.

🔑 SerpApi Setup Guide

Before getting started, you'll need to obtain a SerpApi key. Here's how:

1. Visit SerpApi website and create an account

2. After registration, go to your Dashboard:

   • Locate the "API Key" section
   • Copy your API key
   • New users get 250 free API calls

3. API Usage Details:

   • Free tier: 250 searches per month
   • Paid plans start at $75/month for 5000 searches
   • Billing based on successful API calls
   • Multiple payment methods: Credit Card, PayPal, etc.

4. Usage Limits:

   • Request Rate: 2 requests/second
   • IP Restrictions: None
   • Concurrent Requests: 5
   • Response Cache Time: 1 hour

👩‍🔧 Solution for MCP Servers Connection Issues with NVM/NPM

Click to view my configuration solution 👉 https://github.com/modelcontextprotocol/servers/issues/76

🚀 Quick Start

1. Install dependencies:

npm install

2. Build the server:

npm run build

3. Configure environment: Modify your claude_desktop_config.json with the following content (adjust paths according to your system):

    "google-news": {
      "command": "D:\\Program\\nvm\\node.exe",
      "args": [
        "D:\\github_repository\\path_to\\dist\\index.js"
      ],
      "env": {
        "SERP_API_KEY": "your-api-key"
      }
    }

4. Start the server:

npm start

Troubleshooting

1. Invalid API Key

• Verify API key configuration in claude_desktop_config.json
• Confirm API key is active in SERP API dashboard

2. Request Failures

• Check network connectivity
• Verify API call quota hasn't been exceeded
• Validate request parameter format

Running evals

The evals package loads an mcp client that then runs the index.ts file, so there is no need to rebuild between tests. You can load environment variables by prefixing the npx command. Full documentation can be found here.

OPENAI_API_KEY=your-key  npx mcp-eval src/evals/evals.ts src/index.ts

📦 Installation

Installing via Smithery

To install Google News for Claude Desktop automatically via Smithery:

npx -y @smithery/cli install @chanmeng666/google-news-server --client claude

Installing via mcp-get

npx @michaellatman/mcp-get@latest install @chanmeng666/google-news-server

If you are using an old version of Windows PowerShell, you may need to run Set-ExecutionPolicy Bypass -Scope Process before this command.

Manual Installation

@chanmeng666/google-news-server

# Using npm
npm i @chanmeng666/google-news-server
# or
npm install @chanmeng666/google-news-server

# Using yarn
yarn add @chanmeng666/google-news-server

# Using pnpm
pnpm add @chanmeng666/google-news-server

💻 Tech Stack

📖 API Documentation

The server implements the Model Context Protocol and exposes a Google News search tool with the following parameters:

• q: Search query string
• gl: Country code (e.g., 'us', 'uk')
• hl: Language code (e.g., 'en', 'es')
• topic_token: Token for specific news topics
• publication_token: Token for specific publishers
• story_token: Token for full coverage of a story
• section_token: Token for specific sections

🔧 Development

# Run in development mode with hot reload
npm run dev

# Run linting
npm run lint

# Run tests
npm run test

📝 License

This project is MIT licensed.

🙋‍♀ Author

Created and maintained by Chan Meng.

For AI Agents and LLM Crawlers

This MCP server is optimized for AI agent usage with comprehensive instructions and structured data.

Quick AI Usage Guide

{
  "tool": "google_news_search",
  "parameters": {
    "q": "artificial intelligence latest developments",
    "gl": "us",
    "hl": "en"
  }
}

AI-Friendly Features

• Automatic Categorization: News results are automatically sorted into relevant categories
• Structured Output: Returns formatted data optimized for AI processing
• Multi-language Support: Supports various languages with automatic fallbacks
• Error Handling: Comprehensive error messages and graceful degradation

Response Format

The server returns categorized news with the following structure:

• Categories: AI & Technology, Business, Science & Research, Healthcare, General
• Article Fields: title, source, link, date, snippet, authors
• Metadata: timestamp, menu_links for related topics

Best Practices for AI Agents

1. Use specific, descriptive keywords for better results
2. Leverage automatic categorization for topic-based workflows
3. Implement proper error handling and retry logic
4. Respect API rate limits (2 requests/second)
5. Parse structured responses for better context understanding

Advanced Usage Patterns

• News Monitoring: Use company names or stock symbols for business news
• Research Exploration: Leverage topic tokens for field-specific searches
• Breaking News: Use "breaking news" or "latest news" queries
• Multi-language: Combine appropriate gl and hl parameters

Error Handling

• Invalid API key: Check SERP_API_KEY environment variable
• Unsupported language: Server auto-falls back to English
• Rate limiting: Respect 2 requests/second limit
• Invalid parameters: Validate parameter types before calling

Generative Engine Optimization (GEO) Features

This server includes comprehensive monitoring and optimization for AI agent usage.

Key Metrics Tracked

• Citation Success Rate: Percentage of successful tool calls
• AI Traffic Conversion Rate: Percentage of AI agents successfully using the tool
• Query Coverage Rate: Percentage of queries returning relevant results
• Response Time: Ave