Skip to content

Jakolo121/ARD-MCP-Server

BranchesTags

Repository files navigation

ARD / Tagesschau MCP Server

Verbinde deinen KI-Assistenten direkt mit aktuellen Nachrichten.
Ein produktionsreifer Model Context Protocol (MCP)-Server, der die öffentliche Tagesschau-API nutzt.

pylint tests python license

Sprache:

  • 🇩🇪 Deutsch
  • 🇬🇧 English

Inhaltsverzeichnis

  1. Was ist dieses Projekt?
  2. Features
  3. Projektstruktur
  4. Schnellstart Lokal (Claude Desktop)
  5. Remote / Docker-Deployment
  6. Konfigurationsreferenz
  7. Verfügbare Tools
  8. Verfügbare Ressourcen
  9. Entwicklung
  10. Tests
  11. Makefile-Referenz
  12. Fehlerbehebung
  13. Lizenz & Danksagung

Was ist dieses Projekt?

Dieser MCP-Server verbindet die ARD/Tagesschau-API mit deinem KI-Assistenten (Claude, Open Claw u.a.).

Sobald verbunden, kann der Assistent z.B folgende Anfragen beantworten:

  • „Was sind die aktuellen Schlagzeilen?"
  • „Zeig mir die neuesten Wirtschaftsnachrichten."
  • „Suche nach Artikeln über Ukraine."
  • „Welche Regionalnachrichten gibt es aus Bayern?"

Die API stammt von Tagesschau.

Features
Live-Nachrichten Aktuelle Meldungen, kategorisiert, regional, in Echtzeit
Volltextsuche Über alle verfügbaren Artikel
Livestreams Alle Tagesschau-Kanäle mit HLS-URLs
Dual-Transport stdio lokal; streamable_http für Remote und Docker
Docker Multi-Stage-Build, Nicht-Root-User, Health-Checks, Limits
124 Tests Unit-Tests (< 0,3 s) + Live-Integrationstests
Makefile make test, make lint, make docker-build
Keine Secrets Öffentliche API, kein API-Schlüssel nötig

Projektstruktur

ARD_MCP/
├── src/
│   └── ard_mcp/
│       ├── __init__.py      # Paket-Metadaten
│       ├── config.py        # Umgebungsvariablen
│       ├── client.py        # Async HTTP (httpx) + Fehlerbehandlung
│       ├── validators.py    # Validierung
│       ├── formatters.py    # Markdown-Output
│       ├── tools.py         # MCP-Tool-Logik
│       ├── resources.py     # MCP-Ressourcen-Logik
│       └── server.py        # FastMCP + run()
├── tests/
│   ├── conftest.py          # Fixtures, Mock-Daten
│   ├── test_client.py       # Client-Tests
│   ├── test_formatters.py   # Formatter-Tests
│   ├── test_tools.py        # Tool-Tests
│   └── test_resources.py    # Ressourcen-Tests
├── main.py                  # Einstiegspunkt
├── pyproject.toml           # Abhängigkeiten, Config
├── uv.lock                  # Dependency-Lock
├── Dockerfile               # Produktions-Image
├── docker-compose.yml       # Docker-Deployment
├── .env.example             # Konfigurationsvorlage
├── Makefile                 # Entwickler-Tools
├── CHANGELOG.md             # Versionshistorie
├── CONTRIBUTING.md          # Beiträge
└── README.md                # Diese Datei

Schnellstart Lokal (Bsp. Claude Desktop - gilt aber auch für andere KI-Assistenten)

Der stdio-Transport startet den Server als Subprocess. Es muss kein Port angegeben werden.

Voraussetzungen

Schritt 1: Repository klonen und Projekt installieren

git clone https://github.com/Jakolo121/ard_mcp_server.git
cd ard_mcp_server
uv sync

Schritt 2: Funktionscheck

uv run python -c "from ard_mcp.server import mcp; print('OK!', mcp.name)"
# Erwartete Ausgabe: OK! Tagesschau News API

Schritt 3: Claude Desktop oder andern Aissistenten konfigurieren

Wir nehmen hier Claude Desktop als Beispiel, bei anderen Assistenten die entsprechende Konfig bearbeiten

Öffne die Claude-Konfigurationsdatei:

Betriebssystem Pfad
macOS ~/Library/Application Support/Claude/claude_desktop_config.json
Windows %APPDATA%\Claude\claude_desktop_config.json
Linux ~/.config/Claude/claude_desktop_config.json

Eintrag hinzufügen (Pfad anpassen):

    "tagesschau": {
      "command": "uv",
      "args": [
        "--directory",
        "/absoluter/pfad/zu/ard_mcp_server",
        "run",
        "ard-mcp"
      ]
    },

Schritt 4: Application neu starten

Die Application neustarten oder die MCP-Server neu laden, je nach Application

Schritt 5: Test

Frage KI-Assistenten:

„Was sind die aktuellen Tagesschau-Nachrichten?"

Remote / Docker-Deployment

Der streamable_http-Transport nutzt HTTP. Geeignet für Server, Cloud-VMs oder Multi-Client-Setup. Stateless! Legacy sse wird noch supportet!

Voraussetzungen

Schritt 1: .env erstellen/kopieren

cp .env.example .env
# Bei Bedarf editieren (Port, Log-Level etc.)

Schritt 2: Bauen und starten

docker compose up --build -d

Oder:

make docker-build
make docker-run

Der Server läuft auf http://localhost:8000.

Schritt 3: Status prüfen

docker compose logs ard-mcp
docker compose ps

Oder:

make docker-logs

Schritt 4: Claude Desktop anpassen (Streamable HTTP)

    "tagesschau": {
      "command": "npx",
      "args": ["mcp-remote", "http://localhost:8000/mcp"]
    },

Für externe Server: localhost durch IP oder Domain ersetzen, Port 8000 freigeben.

Stoppen / Aktualisieren

docker compose down
docker compose up --build -d

Konfigurationsreferenz

Alle Einstellungen kommen aus Umgebungsvariablen oder .env.

Variable Standard Beschreibung
TRANSPORT stdio stdio oder streamable_http
PORT 8000 HTTP-Port (nur streamable_http)
LOG_LEVEL INFO DEBUG, INFO, WARNING, ERROR

Verfügbare Tools

Dein Assistent kann diese aufrufen.

get_latest_news

Top-Meldungen abrufen.

Parameter Typ Standard Beschreibung
limit int 10 Maximale Ergebnisse

get_news_by_ressort

Nach Kategorie filtern.

Parameter Typ Standard Beschreibung
ressort str — inland ausland wirtschaft sport video investigativ wissen
limit int 10 Maximale Ergebnisse

Ressort-Strings werden automatisch zu Kleinbuchstaben normalisiert — "Inland", "INLAND" und "inland" sind gleichwertig.

get_regional_news

Regionalnachrichten.

Parameter Typ Standard Beschreibung
region_id int — 1=BW · 2=BY · 3=BE · 4=BB · 5=HB · 6=HH · 7=HE · 8=MV · 9=NI · 10=NRW · 11=RLP · 12=SL · 13=SN · 14=ST · 15=SH · 16=TH
ressort str None Optionaler Kategorie-Filter
limit int 10 Maximale Ergebnisse

search_news

Volltextsuche.

Parameter Typ Standard Beschreibung
search_text str — Suchanfrage
page_size int 10 Ergebnisse pro Seite (max 30)
result_page int 0 Seitenversatz (0-basiert)

get_news

Kombinierte Abfrage — Region + Kategorie.

Parameter Typ Standard Beschreibung
regions str None Region-ID (1–16)
ressort str None Kategorie-Filter
limit int 10 Maximale Ergebnisse

get_channels

Live-Kanäle mit Stream-URLs.

(Keine Parameter)

Verfügbare Ressourcen

URIs, die MCP-Clients lesen können.

URI Beschreibung
tagesschau://homepage Top-Meldungen
tagesschau://news/{ressort} Nachrichten nach Kategorie
tagesschau://regional/{region_id} Regionalnachrichten
tagesschau://search/{search_text} Suchergebnisse
tagesschau://channels Kanäle & Streams

Entwicklung

Setup

git clone https://github.com/Jakolo121/ard_mcp_server.git
cd ard_mcp_server
uv sync --extra dev

Server starten:

uv run ard-mcp

Oder:

make run

Code-Struktur (SOLID)

Jedes Modul hat eine Aufgabe:

Modul Aufgabe
config.py Umgebungsvariablen lesen
client.py HTTP + Fehlerbehandlung
validators.py Eingabevalidierung
formatters.py API-Dicts zu Markdown
tools.py Tool-Logik (validieren, aufrufen, formatieren)
resources.py Ressourcen-Logik
server.py FastMCP, Handler, Startup

Neues Tool

  1. Funktion in tools.py hinzufügen
  2. Mit @mcp.tool() in server.py registrieren
  3. Tests in tests/test_tools.py schreiben

Tests

Unit-Tests (schnell, kein Netz)

uv run pytest
uv run pytest -v
uv run pytest tests/test_formatters.py

Oder:

make test

Live-Tests (braucht Internet)

uv run pytest -m integration
uv run pytest -m integration -v

Alle Tests

uv run pytest -m ""

Oder:

make test-all

Qualität checken (Lint + Tests)

uv run pylint src/ard_mcp/
uv run pytest

Oder:

make check

Erwartete Ergebnisse

124 passed in X s   ← Unit-Tests
 23 selected          ← Integrationstests

Makefile-Referenz

make test          # Unit-Tests (~0,3 s)
make test-all      # Unit- + Integrationstests
make lint          # pylint
make check         # lint + Tests (für CI)
make run           # stdio-Server
make run-http      # HTTP-Server
make docker-build  # Docker bauen
make docker-run    # docker compose up
make docker-stop   # docker compose down
make docker-logs   # Logs folgen
make clean         # __pycache__ etc. löschen

Fehlerbehebung

Claude Desktop zeigt keine Tools

  1. Pfad in claude_desktop_config.json ist absolut?
  2. uv run python main.py startet fehlerlos?
  3. Claude komplett beenden, neu öffnen (Cmd+Q, nicht einfach fenster schließen)

Docker-Container beendet sich sofort

docker compose logs ard-mcp

Oder:

make docker-logs

Häufig: falscher TRANSPORT (in Docker muss es streamable_http sein), oder Port belegt.

API-Timeouts

Die Tagesschau-API limitiert manchmal. Das ist normal, der Server meldet einen Fehler, statt abzustürzen. Später nochmal versuchen.

Import-Fehler bei Tests

uv sync --extra dev
uv run pytest

(Nicht bare pytest verwenden)

Lizenz & Danksagung

Apache License 2.0.

Nachrichteninhalte: ARD / Tagesschau öffentliche Rundfunkdaten, persönliche Nutzung und Forschung.

Danke an AndreasFischer1985 für die Tagesschau-API.

About

Dieser MCP-Server verbindet die ARD/Tagesschau-API mit deinem KI-Assistenten (Claude, Open Claw u.a.).

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

1 watching

Forks

0 forks
Report repository

Releases

No releases published

Packages

 
 
 

Contributors

Languages