Finance News MCP Server

Ein Model Context Protocol (MCP) Server für Finanznachrichten, der echte Nachrichten von NewsAPI abruft und strukturierte, zusammengefasste Antworten liefert.

Features

• 🔍 Nachrichtensuche: Volltextsuche über Finanznachrichten
• 📰 Top Headlines: Aktuelle Schlagzeilen nach Land und Kategorie
• 📡 Quellenverzeichnis: Liste der verfügbaren News-Quellen
• 📊 Strukturierte Output: JSON mit Bullet-Points und Zusammenfassungen

---

Schnellstart

1. Virtualenv + Abhängigkeiten

python3 -m venv .venv
source .venv/bin/activate
pip install -e .

macOS/Linux-Spezifika:

• Falls python nicht existiert, nutze python3
• source für Bash/Zsh (nicht Windows PowerShell)

2. .env Datei erstellen

cp .env.example .env

Öffne .env und trage deine NewsAPI Credentials ein:

NEWS_API_KEY=dein_api_key_von_newsapi_org

NewsAPI Key besorgen (kostenlos mit täglichem Limit).

3. Server starten

python mcp_server.py

Erwartet einen MCP-Client, der über STDIO Anfragen sendet.

---

Testing & Debugging

Option A: Direkt die Handler testen

Führe die Handler-Funktionen direkt auf, ohne STDIO zu nutzen:

python test_handlers.py

Nützlich für:

• Schnelle Funktionstests
• Debugging ohne External-Dependencies
• API-Antworten prüfen

Option B: Mit dem STDIO-Client testen

Starte den Server als Unterprozess und kommuniziere per JSON-RPC:

python stdio_client.py

Beispiele mit verschiedenen Parametern:

# Standard-Ausführung (Apple earnings, US, englisch, 3 Ergebnisse)
python stdio_client.py

# Andere Suchanfrage
python stdio_client.py --search "Tesla stock"

# Mit Land und Sprache
python stdio_client.py --search "Fed interest rate" --country gb --language de

# Mehr Ergebnisse
python stdio_client.py --country us --page-size 10

# Deutsche Quellen
python stdio_client.py --language de --country de

# Bitcoin News aus Großbritannien
python stdio_client.py --search "Bitcoin" --country gb

# Hilfe anzeigen
python stdio_client.py --help

---

STDIO Client Parameter

Der stdio_client.py akzeptiert folgende Argumente:

Parameter	Typ	Default	Beispiel	Beschreibung
--search	text	"Apple earnings"	--search "Tesla"	Suchanfrage für Finanznachrichten
--country	text	"us"	--country gb	Ländercode (ISO 3166-1 alpha-2) für Headlines
--language	text	"en"	--language de	Sprachcode (ISO 639-1) für Quellen
--page-size	integer	3	--page-size 10	Anzahl Ergebnisse (1-50)

Wie der Parser funktioniert

Der argparse.ArgumentParser in stdio_client.py verarbeitet Kommandozeilen-Argumente:

parser.add_argument("--search", type=str, default=None, 
                    help='Search query for finance news')

Das bedeutet:

• --search ist der Schalter
• type=str erwartet einen Text-String
• default=None = wenn nicht angegeben, ist der Wert None
• In main() wird mit or ein Fallback-Wert gesetzt

Praktisch:

# Mit Argumenten
python stdio_client.py --search "Bitcoin" --country de

# Ohne Argumente
python stdio_client.py  # nutzt alle Defaults

---

Response-Struktur

Typische Antwort bei search_finance_news:

{
  "metadata": {
    "query": "Apple earnings",
    "language": "en",
    "sort_by": "publishedAt",
    "total_results": 5
  },
  "articles": [
    {
      "title": "Apple Q2 Earnings Beat Expectations",
      "source": "Bloomberg",
      "url": "https://...",
      "published_at": "2026-05-30T14:00:00Z",
      "summary": "• Apple beat earnings estimates\n• Revenue up 12% YoY\n• Services segment grew 15%",
      "key_points": [
        "Apple beat earnings estimates",
        "Revenue up 12% YoY",
        "Services segment grew 15%"
      ]
    }
  ]
}

---

Tools

Der Server implementiert 3 MCP-Tools:

1. search_finance_news

Volltextsuche über Finanznachrichten.

Parameter:

• query (erforderlich): Suchanfrage, z.B. "Apple earnings", "Fed rate", "Bitcoin"
• language (optional): ISO 639-1 Code (default: "en")
• page_size (optional): 1-50 (default: 5)
• sort_by (optional): "relevancy", "popularity", "publishedAt" (default: "publishedAt")

2. get_top_finance_headlines

Aktuelle Top-Headlines nach Land/Kategorie.

Parameter:

• country (optional): ISO 3166-1 alpha-2 Code, z.B. "us", "gb", "de"
• category (optional): "business", "technology", etc. (default: "business")
• page_size (optional): 1-50 (default: 5)

3. get_finance_sources

Liste der verfügbaren Nachrichtenquellen.

Parameter:

• language (optional): ISO 639-1 Code
• country (optional): ISO 3166-1 Code
• category (optional): Nachrichtenkategorie

---

Projektstruktur

mcp_server/
├── mcp_server.py          # MCP Server (Haupt-Einstiegspunkt)
├── stdio_client.py        # Test-Client mit Kommandozeilen-Args
├── test_handlers.py       # Direkte Handler-Tests (ohne STDIO)
├── test_news_api.py       # Debug-Skript für NewsAPI
├── news_client.py         # NewsAPI HTTP-Client
├── models.py              # Pydantic Modelle für Validierung
├── summarizer.py          # Artikel→Bullet-Points Transformation
├── config.py              # Konfiguration (Env Vars)
├── pyproject.toml         # Package-Metadaten & Dependencies
├── .env.example           # Beispiel Env-Datei
└── README.md              # Diese Datei

---

Beispiel-Kommandos

# Nachrichten zu Tesla suchen
python stdio_client.py --search "Tesla" --page-size 5

# Top Headlines Großbritannien
python stdio_client.py --country gb --page-size 10

# Fed & Zinsen (mit Deutsche Quellen)
python stdio_client.py --search "Federal Reserve" --language de

# Kryptowährungen weltweit
python stdio_client.py --search "Bitcoin crypto" --page-size 15

# Test aller Tools auf einmal
python stdio_client.py

---

Lizenz & Credits

• NewsAPI: newsapi.org
• MCP Protocol: Model Context Protocol
• FastAPI/Pydantic: Type-safe Python