News MCP

🚀 📰 News MCP Server

A smart news search MCP (Model Context Protocol) server with automatic API switching for reliable news fetching. Never worry about API limits again!

✨ Features

• 🔄 Smart API Switching: Automatically switches between multiple news APIs when one reaches its limit.
• 🆓 Multiple Free APIs: Supports 5+ free news APIs with generous daily quotas.
• 📊 Quota Management: Intelligent tracking of daily API usage limits.
• 🌍 Multi-language Support: Search news in 20+ languages.
• ⚡ Fast & Reliable: Failover mechanism ensures you always get results.
• 🛠️ Easy Setup: Simple configuration with environment variables.

🚀 Quick Start

1. Installation

# Clone the repository
git clone https://github.com/guangxiangdebizi/news-mcp.git
cd news-mcp

# Install dependencies
npm install

# Copy environment template
cp .env.example .env

2. API Configuration

Get free API keys from any of these services (you only need one, but more = better reliability):

*Claimed unlimited for free tier

3. Configure Environment

Edit the .env file and add your API keys:

# Add at least one API key (more is better for reliability)
THE_NEWS_API_KEY=your_api_key_here
NEWSDATA_IO_KEY=your_api_key_here
NEWSAPI_ORG_KEY=your_api_key_here
GNEWS_API_KEY=your_api_key_here
TWINGLY_API_KEY=your_api_key_here

4. Build & Run

# Build the project
npm run build

# Start the MCP server
npm start

# Or run in development mode
npm run dev

💻 Usage Examples

With Claude Desktop

Add to your Claude Desktop configuration:

Stdio Mode (Local Development):

{
  "mcpServers": {
    "news-mcp": {
      "command": "node",
      "args": ["path/to/news-mcp/build/index.js"]
    }
  }
}

SSE Mode (Web Access):

# Start SSE server
npm run sse

{
  "mcpServers": {
    "news-mcp": {
      "type": "sse",
      "url": "http://localhost:3100/sse",
      "timeout": 600
    }
  }
}

Available Tools

search_news

Search for news articles with automatic API switching.

Parameters:

• query (required): Search keywords or topics.
• language (optional): Language code (default: "en").
• limit (optional): Number of articles (1 - 10, default: 5).

Example:

// Search for technology news
{
  "query": "artificial intelligence",
  "language": "en",
  "limit": 5
}

// Search for Chinese news
{
  "query": "科技新闻",
  "language": "zh",
  "limit": 3
}

🔧 Technical Details

How Smart Switching Works

1. Priority Order: APIs are tried in order of reliability and quota limits.
2. Quota Tracking: System tracks daily usage for each API.
3. Automatic Failover: When an API fails or reaches limit, automatically tries the next one.
4. Success Guarantee: Continues until successful response or all APIs exhausted.

TheNewsAPI (∞) → NewsData.io (200) → NewsAPI.org (100) → GNews (100) → Twingly (50)

Supported Languages

• English (en) - All APIs
• Chinese (zh) - Most APIs
• Spanish (es) - Most APIs
• French (fr) - Most APIs
• German (de) - Most APIs
• And 15+ more languages

🛠️ Development

Project Structure

src/
├── index.ts              # MCP server entry point
├── config.ts             # API configuration management
└── tools/
    └── newsSearch.ts     # Smart news search tool

Scripts

npm run build     # Build TypeScript
npm run dev       # Development mode with watch
npm start         # Start built server
npm run sse       # Start SSE server on port 3100

Adding New APIs

1. Add API configuration to src/config.ts.
2. Implement API-specific request logic in src/tools/newsSearch.ts.
3. Add environment variable to .env.example.

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

1. Fork the repository.
2. Create your feature branch (git checkout -b feature/AmazingFeature).
3. Commit your changes (git commit -m 'Add some AmazingFeature').
4. Push to the branch (git push origin feature/AmazingFeature).
5. Open a Pull Request.

📄 License

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

👨‍💻 Author

Xingyu Chen

• 🌐 Website: GitHub Profile
• 📧 Email: guangxiangdebizi@gmail.com
• 💼 LinkedIn: Xingyu Chen
• 📦 NPM: @xingyuchen

🙏 Acknowledgments

• Model Context Protocol for the amazing MCP framework.
• All the news API providers for their generous free tiers.
• The open-source community for inspiration and support.

⭐ If this project helped you, please give it a star!