README.md•5.93 kB
# 📰 News MCP Server
[](https://opensource.org/licenses/Apache-2.0)
[](https://www.typescriptlang.org/)
[](https://modelcontextprotocol.io/)
A smart news search MCP (Model Context Protocol) server with **automatic API switching** for reliable news fetching. Never worry about API limits again!
<a href="https://glama.ai/mcp/servers/@guangxiangdebizi/news-mcp">
<img width="380" height="200" src="https://glama.ai/mcp/servers/@guangxiangdebizi/news-mcp/badge" alt="News Server MCP server" />
</a>
## ✨ 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
```bash
# 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):
| Service | Daily Limit | Sign Up Link | Priority |
|---------|-------------|--------------|----------|
| **TheNewsAPI** | Unlimited* | [Get Key](https://www.thenewsapi.com/) | 🥇 Highest |
| **NewsData.io** | ~200 requests | [Get Key](https://newsdata.io/) | 🥈 High |
| **NewsAPI.org** | 100 requests | [Get Key](https://newsapi.org/register) | 🥉 Medium |
| **GNews** | 100 requests | [Get Key](https://gnews.io/) | 🏅 Medium |
| **Twingly** | Trial available | [Get Key](https://www.twingly.com/news-api/) | 🎖️ Low |
*\*Claimed unlimited for free tier*
### 3. Configure Environment
Edit `.env` file and add your API keys:
```env
# 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
```bash
# Build the project
npm run build
# Start the MCP server
npm start
# Or run in development mode
npm run dev
```
## 🔧 Usage
### With Claude Desktop
Add to your Claude Desktop configuration:
**Stdio Mode** (Local Development):
```json
{
"mcpServers": {
"news-mcp": {
"command": "node",
"args": ["path/to/news-mcp/build/index.js"]
}
}
}
```
**SSE Mode** (Web Access):
```bash
# Start SSE server
npm run sse
```
```json
{
"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:**
```typescript
// Search for technology news
{
"query": "artificial intelligence",
"language": "en",
"limit": 5
}
// Search for Chinese news
{
"query": "科技新闻",
"language": "zh",
"limit": 3
}
```
## 🧠 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
```bash
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](LICENSE) file for details.
## 👨💻 Author
**Xingyu Chen**
- 🌐 Website: [GitHub Profile](https://github.com/guangxiangdebizi/)
- 📧 Email: guangxiangdebizi@gmail.com
- 💼 LinkedIn: [Xingyu Chen](https://www.linkedin.com/in/xingyu-chen-b5b3b0313/)
- 📦 NPM: [@xingyuchen](https://www.npmjs.com/~xingyuchen)
## 🙏 Acknowledgments
- [Model Context Protocol](https://modelcontextprotocol.io/) 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!**