<p align="center">
  <h1 align="center">🌍 Global News Intelligence MCP</h1>
  <p align="center">
    <strong>A high-performance MCP server delivering structured global news to LLMs.</strong>
    <br/>
    28 RSS sources · 12 categories · 16 tools · MIT licensed
  </p>
</p>

<p align="center">
  <img src="https://img.shields.io/badge/python-3.10%2B-blue" alt="Python">
  <img src="https://img.shields.io/badge/fastmcp-3.4-green" alt="FastMCP">
  <img src="https://img.shields.io/badge/license-MIT-yellow" alt="License">
  <img src="https://img.shields.io/badge/platform-Windows%20%7C%20Linux%20%7C%20macOS-lightgrey" alt="Platform">
</p>

---

## Why This Exists

LLMs are only as good as their information. This MCP server gives your AI agent
real-time access to curated, ranked, and summarized global news — with technology
and AI coverage prioritized.

It is not a simple RSS reader. Every article passes through a pipeline:

```
RSS Fetch → Parse → Classify → Rank by Importance → Summarize → JSON Response
```

Built for [XiaoZhi AI](https://xiaozhi.me) but compatible with any MCP client
(Claude Desktop, Codex, Continue, Cursor, etc.).

---

## Features

- **16 dedicated MCP tools** — one per news category, plus headline and summary tools
- **28 RSS sources** across technology, AI, hardware, open source, international, politics, finance, military, space, energy, entertainment, and domestic (China)
- **Smart ranking** — articles scored by source credibility, keyword relevance, and recency
- **SQLite cache** — 15-minute TTL eliminates redundant fetches; survives network outages
- **Proxy support** — configurable HTTP/HTTPS proxy for mainland China environments
- **Fault isolation** — a single failing source never crashes the server; degrades gracefully to cache
- **Zero API keys** — works entirely on public RSS feeds, no registration required
- **Cross-platform** — Windows, Linux, macOS; Python 3.10+

---

## Quick Start

```bash
git clone https://github.com/ashtondebug/global-news-intelligence-mcp.git
cd global-news-intelligence-mcp

python -m venv .venv
source .venv/bin/activate   # macOS/Linux
# .venv\Scripts\activate    # Windows

pip install -e .
cp config.example.yaml config.yaml
```

### Environment Check

```bash
python check_env.py
```

```
Global News Intelligence MCP - Environment Check

  Python 3.12.13: OK
  fastmcp: OK      httpx: OK      feedparser: OK
  pyyaml: OK       pydantic: OK

Result: ALL CHECKS PASSED
```

### Start

```bash
python -m global_news_mcp
```

The server listens on stdio. Connect it to your MCP client.

---

## MCP Tools

| Tool | Description |
|------|-------------|
| `get_top_news` | Top global headlines (tech/AI prioritized) |
| `get_news` | News by category with configurable limit |
| `get_technology_news` | AI, chips, software, hardware, open source |
| `get_ai_news` | Artificial intelligence |
| `get_hardware_news` | CPUs, GPUs, semiconductors, devices |
| `get_opensource_news` | Open source community and developer ecosystem |
| `get_space_news` | Space missions, science, technology |
| `get_international_news` | Global events from BBC, Reuters, Guardian |
| `get_politics_news` | Political coverage |
| `get_finance_news` | Markets, economy, business |
| `get_military_news` | Defense and security |
| `get_world_news` | Composite: international + politics + finance + military |
| `get_domestic_news` | China news (People s Daily, China News, NetEase, IT Home, 36Kr) |
| `get_energy_news` | Oil, gas, renewables, energy policy |
| `get_entertainment_news` | Entertainment industry |
| `get_news_summary` | Summary for a specific article URL |

### Response Format

```json
[
  {
    "title": "OpenAI Announces GPT-5",
    "source": "TechCrunch",
    "time": "2026-08-04T10:30:00+00:00",
    "summary": "OpenAI has officially announced GPT-5, their next-generation...",
    "url": "https://techcrunch.com/2026/08/04/...",
    "category": "ai"
  }
]
```

Up to 10 articles per response, ranked by importance.

---

## Configuration

`config.yaml` (copy from `config.example.yaml`):

```yaml
network:
  timeout: 15
  proxy:
    enabled: false       # Set to true for mainland China
    http: ""             # e.g. http://127.0.0.1:7890  (Clash)
    https: ""            # e.g. http://127.0.0.1:7890

cache:
  ttl: 900              # Seconds (15 min)

logging:
  level: "INFO"
  file: ""              # Empty = stderr only

sources:
  technology: true       # Toggle individual categories
  ai: true
  # ... 12 categories total
```

**Common proxy ports:** Clash `7890` · V2Ray `10809` · SSR `1080`

---

## Architecture

```
┌──────────────────────────────────────┐
│           MCP Client (LLM)            │
│   XiaoZhi AI / Claude / Codex / ...   │
└──────────────────┬───────────────────┘
                   │ stdio (JSON-RPC)
┌──────────────────▼───────────────────┐
│          main.py (FastMCP)            │
│         16 registered tools           │
└──┬───────┬──────┬───────┬────────────┘
   │       │      │       │
   ▼       ▼      ▼       ▼
┌──────┐ ┌────┐ ┌──────┐ ┌──────────┐
│ rss  │ │cache│ │ranking│ │summarizer│
│ .py  │ │ .py │ │ .py  │ │   .py    │
└──┬───┘ └──┬─┘ └──┬───┘ └────┬─────┘
   │        │      │          │
   ▼        ▼      ▼          ▼
┌──────┐ ┌──────┐ ┌──────┐ ┌──────────┐
│parser│ │SQLite│ │sources│ │classifier│
│ .py  │ │  DB  │ │ .py  │ │   .py    │
└──────┘ └──────┘ └──────┘ └──────────┘
```

Pipeline: **Sources → Fetch → Parse → Classify → Rank → Summarize → Return**

---

## News Sources

| Category | Sources |
|----------|---------|
| **Technology** | The Verge, TechCrunch, Ars Technica, MIT Technology Review |
| **AI** | OpenAI Blog, DeepMind Blog, Hugging Face Blog |
| **Hardware** | Tom s Hardware, AnandTech |
| **Open Source** | Hacker News |
| **International** | BBC News, Reuters World, The Guardian |
| **Politics** | BBC Politics |
| **Finance** | Reuters Business, CNBC |
| **Military** | Defense News |
| **Space** | Space.com, SpaceNews, NASA Releases, ESA Space Science |
| **Energy** | OilPrice |
| **Entertainment** | Variety |
| **Domestic (China)** | People s Daily, China News, NetEase News, IT Home, 36Kr |

28 feeds total. To add a source, edit `src/global_news_mcp/sources.py`:

```python
{"name": "My Source", "url": "https://example.com/rss", "category": "technology"},
```

---

## Client Integration

### Claude Desktop

```json
{
  "mcpServers": {
    "global_news": {
      "command": "python",
      "args": ["-m", "global_news_mcp"],
      "cwd": "/path/to/global-news-intelligence-mcp"
    }
  }
}
```

### Codex / Continue / Cursor

Same pattern — point the `command` to your Python and set `cwd` to the project root.

---

## Development

```bash
pip install -e ".[dev]"
pytest
```

### Code Conventions

- `logging` only — never `print()` (stdout is JSON-RPC)
- `pathlib` for all filesystem paths
- UTF-8 throughout
- Every `@mcp.tool()` function must have a complete docstring

### Adding a New Tool

```python
@mcp.tool()
async def get_my_category_news() -> str:
    """Get news for my custom category."""
    return await _fetch_news(["my_category"], 10)
```

---

## Project Structure

```
.
├── pyproject.toml
├── config.example.yaml
├── README.md
├── RUNBOOK.md
├── check_env.py
├── install.bat
├── start.bat
├── src/global_news_mcp/
│   ├── main.py          # Entry point + 16 tool registrations
│   ├── sources.py       # 28 RSS feed definitions
│   ├── rss.py           # Async concurrent fetching
│   ├── parser.py        # feedparser → Article model
│   ├── classifier.py    # Keyword-based classification
│   ├── ranking.py       # Importance scoring
│   ├── summarizer.py    # Response formatting
│   ├── cache.py         # SQLite cache layer
│   ├── network.py       # httpx client (proxy/timeout)
│   ├── config.py        # YAML config loader
│   └── logger.py        # stderr logging
└── .gitignore
```

---

## License

MIT © 2026