Football Intelligence MCP

Ein lokaler Model Context Protocol-Server, der jedem MCP-Host – Claude Desktop, Claude Code oder einem eigenen Chatbot – Zugriff auf eine kuratierte historische Fußballdatenbank mit 36.982 Spielen aus den sieben besten europäischen Wettbewerben von 2010 bis 2025 bietet.

Das Protokoll ist direkt über JSON-RPC 2.0 implementiert, ohne ein MCP-SDK zu verwenden: Jede Nachricht wird manuell gemäß der 2025-06-18-Spezifikation erstellt und geparst.

Was in der Datenbank enthalten ist

Die Daten stammen ursprünglich von API-Football und wurden in PostgreSQL normalisiert.

Bekannte Abdeckungsgrenzen

Der Server meldet diese, anstatt zu raten, und Sie sollten es auch tun:

• Spielstatistiken beginnen 2015. Die Saisons 2010–2014 enthalten Ergebnisse, Tore, Ereignisse und Aufstellungen, aber keine Schüsse, Ballbesitz- oder Passdaten.

• Expected Goals (xG) gibt es erst ab 2023 und nie für die Champions League.

• Aufstellungs- und Trainerdaten beginnen 2015.

• Bei 58 Spielen (0,16 %) fehlt ein Tor in der Ereignisliste – eine Lücke in API-Football. Die Endergebnisse sind davon nicht betroffen; sie stammen aus dem Spielbericht, nicht aus der Summierung von Ereignissen.

Rufen Sie das Tool data_coverage auf, um zu prüfen, was für eine beliebige Liga und Saison vorhanden ist.

Installation

Erfordert Python 3.10+ und PostgreSQL 14+.

git clone https://github.com/jaq23369/football-intelligence-mcp.git
cd football-intelligence-mcp

python -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt

createdb football
pg_restore -d football data/football.dump

cp .env.example .env      # edit DATABASE_URL if your setup differs

Überprüfen Sie die Wiederherstellung:

psql -d football -c "SELECT count(*) FROM fixtures;"
#  count
# -------
#  36982

Den Server ausführen

python server.py

Der Server spricht JSON-RPC über stdio. Er wird normalerweise von einem MCP-Host gestartet und nicht von Hand, aber Sie können ihn direkt steuern:

printf '%s\n' \
  '{"jsonrpc":"2.0","id":1,"method":"initialize","params":{"protocolVersion":"2025-06-18","capabilities":{},"clientInfo":{"name":"manual","version":"1.0"}}}' \
  '{"jsonrpc":"2.0","id":2,"method":"tools/list"}' \
  | python server.py

Claude Desktop

Fügen Sie Folgendes zu claude_desktop_config.json hinzu:

{
  "mcpServers": {
    "football": {
      "command": "/absolute/path/to/football-intelligence-mcp/.venv/bin/python",
      "args": ["/absolute/path/to/football-intelligence-mcp/server.py"]
    }
  }
}

Claude Code

claude mcp add football -- /absolute/path/to/.venv/bin/python /absolute/path/to/server.py

Protokoll

Transport: stdio, zeilenumbruchgetrenntes JSON. Protokollversion 2025-06-18.

Fehler folgen JSON-RPC 2.0: -32700 Parse-Fehler, -32600 ungültige Anfrage, -32601 Methode nicht gefunden, -32602 ungültige Parameter, -32603 interner Fehler.

Fehler auf Tool-Ebene sind keine JSON-RPC-Fehler – sie geben ein normales Ergebnis mit isError: true zurück, damit das Modell die Nachricht lesen und sich erholen kann.

stdout überträgt nur JSON-RPC. Alle Diagnosen gehen an stderr.

Tools

search_team

Findet Teams anhand von Teilnamen, sortiert nach der Anzahl der gespeicherten Spiele. Rufen Sie dies zuerst auf – jedes andere Team-Tool benötigt eine team_id.

{"name": "search_team", "arguments": {"query": "Liverpool", "limit": 1}}

[{"team_id": 40, "name": "Liverpool", "country": "England",
  "founded": 1892, "partidos": 762,
  "primera_temporada": 2010, "ultima_temporada": 2025}]

search_player

Findet Spieler anhand des Namens, sortiert nach gespielten Minuten.

get_match

Vollständiger Spielbericht: Ergebnis, Austragungsort, Schiedsrichter, Statistiken pro Team und jedes Tor mit Minute und Vorlage. Spiele vor 2015 geben einen expliziten Hinweis zurück, anstatt leerer Statistiken.

get_team_form

Aktuelle Form: Serie, Punkte, Tore für und gegen.

before beschränkt die Berechnung auf Spiele, die strikt vor diesem Datum liegen, sodass Sie den Zustand eines Teams zu jedem vergangenen Zeitpunkt rekonstruieren können. Dies ist der Schutz gegen Look-Ahead-Bias beim Erstellen von Vorhersagemerkmalen.

{"name": "get_team_form",
 "arguments": {"team_id": 40, "last": 5, "before": "2020-01-01"}}

get_head_to_head

Bilanz aus Siegen/Unentschieden/Niederlagen zwischen zwei Teams, ihre letzten Begegnungen und Durchschnittswerte pro Team (Tore pro Spiel, Gelbe/Rote Karten, Fouls, Ecken) über ihre gesamte Geschichte – nützlicher Kontext für eine Wettentscheidung, nicht nur eine Vorhersagezahl. Karten/Fouls/Ecken sind nur für Spiele ab 2015 verfügbar; Spiele ohne Statistiken werden aus diesen Durchschnittswerten ausgeschlossen, nicht als Null gezählt.

get_team_season

Endplatzierung in der Liga, Punkte und Tore, zusammen mit Durchschnittswerten pro Spiel für Schüsse, Ballbesitz, Ecken und Passgenauigkeit.

Saisons werden nach ihrem Startjahr benannt: 2024 bedeutet die Saison 2024-25.

get_player_season

Saisonweise Spielerwerte, aggregiert aus Spielprotokollen: Tore, Vorlagen, Minuten, Schüsse, Torschussvorlagen, Karten und durchschnittliche Bewertung.

compare_teams

Aktuelle Form für zwei Teams plus ihre direkte Bilanz in einem Aufruf.

compare_players

Die Gesamtwerte zweier Spieler für dieselbe Saison, nebeneinander.

data_coverage

Was tatsächlich in der Datenbank vorhanden ist, pro Liga und Saison. Verwenden Sie es, bevor Sie behaupten, ein Datenpunkt fehle.

predict_match

Wahrscheinlichkeit für Sieg/Unentschieden/Niederlage eines Spiels, basierend auf einem Modell, das mit 23.168 Spielen (2015–2025, sechs nationale Ligen – Champions League ausgenommen, da ihr K.o.-Format nicht mit einer Ligatabelle vergleichbar ist) trainiert wurde. Zwei Kandidaten wurden in einer zurückgehaltenen Validierungssaison direkt verglichen (logistische Regression vs. ein Gradient-Boosted-Trees-Klassifikator); derjenige mit dem besseren Validierungs-Log-Loss wurde behalten. Siehe model.metricas_prueba_2025 in der Antwort des Tools selbst für den ehrlichen, während der Auswahl nie berührten Testwert.

Das Spiel muss nicht bereits in der Datenbank vorhanden sein. Das aktuelle Elo, die aktuelle Form und die Ruhetage jedes Teams werden in einem team_current_form-Snapshot gespeichert, der unabhängig von einem einzelnen Spiel aktualisiert wird – das funktioniert also für ein für nächste Woche geplantes Spiel genauso gut wie für ein vor fünf Jahren ausgetragenes.

{"name": "predict_match", "arguments": {"home_team_id": 529, "away_team_id": 531}}

{
  "local": "Barcelona", "visitante": "Athletic Club",
  "probabilidad_local": 0.779, "probabilidad_empate": 0.145, "probabilidad_visitante": 0.076,
  "modelo": "logistic_regression",
  "advertencia": "Probabilidad estadistica basada en historial, no una garantia..."
}

Das trainierte Modell wird in data/predict_model.joblib ausgeliefert (ein paar KB – eine angepasste scikit-learn-Pipeline, keine rohen Gewichte). Ein erneutes Training erfordert die vollständige Feature-Pipeline (conocimiento/ml/), die sich im privaten Projekt-Repository befindet, nicht hier – dasselbe Verhältnis wie data/football.dump zur Extraktions-Pipeline, die es erstellt hat.

Beispielsitzung

Welches Team hat 2015 die Premier League gewonnen?

→ search_team {"query": "Leicester"}
→ get_team_season {"team_id": 46, "league_id": 39, "season": 2015}

Leicester City, mit 81 Punkten aus 23 Siegen, 12 Unentschieden und 3 Niederlagen – und nur 42,7 % durchschnittlichem Ballbesitz, ungewöhnlich für einen Meister.

Architektur

MCP host  ──JSON-RPC/stdio──>  server.py  ──>  knowledge/engine.py  ──>  PostgreSQL

server.py besitzt das Protokoll und sonst nichts. Die gesamte Abfragelogik befindet sich in knowledge/engine.py, das einfache Wörterbücher zurückgibt und keine Kenntnis von MCP hat – es kann also vollständig eigenständig getestet oder wiederverwendet werden.

Lizenz

MIT. Die Fußballdaten stammen von API-Football und werden hier für akademische Zwecke weitergegeben.

Erstellt für CC3067 Redes, Universidad del Valle de Guatemala.