Football Intelligence MCP

ローカルで動作するModel Context Protocolサーバー。Claude Desktop、Claude Code、カスタムチャットボットなど、あらゆるMCPホストに、2010年から2025年までのヨーロッパ主要7リーグ36,982試合をカバーする厳選されたサッカー歴史データベースへのアクセスを提供します。

プロトコルはMCP SDKを一切使わず、JSON-RPC 2.0で直接実装されています。すべてのメッセージは2025-06-18仕様に従って手作業で構築・解析されます。

データベースの内容

データは元々API-Footballから抽出され、PostgreSQLに正規化されています。

既知のカバレッジ制限

サーバーは推測せずにこれらを報告します。あなたも同様にすべきです:

• 試合統計は2015年から。 2010〜2014年のシーズンには結果、ゴール、イベント、ラインナップはありますが、シュート、ポゼッション、パスのデータはありません。

• 期待ゴール値(xG)は2023年以降のみ存在し、チャンピオンズリーグでは決して利用できません。

• フォーメーションと監督データは2015年から。

• 58試合(0.16%)でイベントリストにゴールが1つ欠落しています — API-Footballの上流側の欠落です。スコアラインには影響ありません。スコアはイベントの合計ではなく、fixtureレコードから取得されます。

data_coverageツールを呼び出すと、任意のリーグとシーズンに何が存在するかを確認できます。

インストール

Python 3.10+ と 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

リストアを確認:

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

サーバーの実行

python server.py

サーバーはstdio上でJSON-RPCを話します。通常はMCPホストによって起動されますが、直接操作することもできます:

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

claude_desktop_config.json に追加:

{
  "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

プロトコル

トランスポート: stdio、改行区切りJSON。プロトコルバージョン 2025-06-18。

エラーはJSON-RPC 2.0に従います: -32700 パースエラー、-32600 無効なリクエスト、-32601 メソッドが見つからない、-32602 無効なパラメータ、-32603 内部エラー。

ツールレベルの失敗はJSON-RPCエラーではありません — isError: true を含む通常の結果を返すため、モデルはメッセージを読んで回復できます。

stdoutはJSON-RPCのみを運びます。 すべての診断情報はstderrに出力されます。

ツール

search_team

部分一致のチーム名で検索し、記録上の試合数が多い順にランク付けします。最初にこれを呼び出してください — 他のすべてのチームツールは 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

選手名で検索し、プレー時間が多い順にランク付けします。

get_match

完全な試合記録: スコア、会場、審判、チーム別統計、分とアシスト付きの全ゴール。2015年より前の試合では、空の統計の代わりに明示的な注記が返されます。

get_team_form

最近の調子: 連勝/連敗、勝ち点、得点と失点。

before は計算をその日付より厳密に前の試合に制限するため、過去の任意の時点でのチームの状態を再構築できます。これは予測特徴量を構築する際のルックアヘッドバイアスに対する防御です。

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

get_head_to_head

2チーム間の勝敗/引き分けバランス、直近の対戦、そして全歴史にわたるチーム別平均(1試合あたりのゴール、イエロー/レッドカード、ファウル、コーナーキック) — 予測数値だけでなく、賭けを決めるための有用なコンテキストです。カード/ファウル/コーナーは2015年以降の試合でのみ利用可能です。統計のない試合はゼロとして数えず、それらの平均から除外されます。

get_team_season

最終順位、勝ち点、ゴールに加え、シュート、ポゼッション、コーナーキック、パス精度の1試合あたり平均。

シーズンは開始年の名前で呼ばれます: 2024 は2024-25シーズンを意味します。

get_player_season

試合レベルの記録から集計されたシーズン別選手トータル: ゴール、アシスト、プレー時間、シュート、キーパス、カード、平均評価。

compare_teams

2チームの最近の調子と対戦成績を1回の呼び出しで。

compare_players

同じシーズンの2選手のトータルを並べて比較。

data_coverage

リーグとシーズンごとに、データベースに実際に何が存在するか。データポイントが欠落していると主張する前に使用してください。

predict_match

試合の勝敗/引き分け確率。23,168試合(2015〜2025年、国内6リーグ — チャンピオンズリーグは除外。ノックアウト形式は総当たりのテーブルと比較できないため)でトレーニングされたモデルから算出されます。2つの候補が保持された検証シーズンで直接比較されました(ロジスティック回帰 vs. 勾配ブースティング木分類器)。検証ログ損失が優れていた方が採用されました。正直な、選択中に一切触れられていないテストスコアについては、ツール自身のレスポンスの model.metricas_prueba_2025 を参照してください。

試合はデータベースに既に存在する必要はありません。各チームの現在のElo、最近の調子、休息日数は team_current_form スナップショットに保持され、個々の試合とは独立に更新されます — そのため、来週予定の試合でも5年前に行われた試合でも同様に機能します。

{"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..."
}

トレーニング済みモデルは data/predict_model.joblib に同梱されています(数KB — 適合済みのscikit-learnパイプラインであり、生の重みではありません)。再トレーニングには完全な特徴量パイプライン(conocimiento/ml/)が必要ですが、これはここではなくプライベートプロジェクトリポジトリにあります — data/football.dump とそれを構築した抽出パイプラインの関係と同じです。

セッション例

2015年のプレミアリーグで優勝したのはどのチームですか?

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

レスター・シティです。23勝12分3敗で81ポイント、平均ポゼッションはわずか42.7% — 優勝チームとしては異例です。

アーキテクチャ

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

server.py はプロトコルだけを担当し、それ以外は何も持ちません。すべてのクエリロジックは knowledge/engine.py にあり、プレーンな辞書を返し、MCPについての知識はありません — そのため、完全に単独でテストしたり再利用したりできます。

ライセンス

MIT。サッカーデータはAPI-Footballに由来し、学術利用のためにここで再配布されています。

グアテマラ・デル・バジェ大学 CC3067 Redes のために構築されました。