Fantasy Premier League (FPL)

fpl-mcp

Claude、ChatGPT、Grok、Cursor、VS Code など、あらゆる MCP クライアントで動作する、Fantasy Premier League 向けのオープンソース MCP サーバーです。公式 FPL API からリアルタイムデータを取得し、vaastav dataset から過去シーズン（2016-17 以降）のデータを取得します。全選手の次の 5 ゲームウィークのポイントを予測し、スカッド、移籍、キャプテン、チップを提案します。データは SQLite または Supabase に保存されます。

インストールせずに試す：

• リモート URL：https://fpl-mcp-9tiv.onrender.com/mcp（claude.ai、ChatGPT、Grok、Cursor。［AI クライアントの接続］(#connecting-ai-clients)を参照）
• npm：ローカルサーバーを実行するアプリ（Claude Desktop、Cursor、VS Code）向けに npx -y fpl-mcp-server
• Smithery および公式 MCP Registry（io.github.GilbertKamau/fpl-mcp）

ホスト型サーバーは無料プランで稼働しているため、しばらくアクセスがない場合、最初のリクエストに 1 分ほどかかることがあります。

質問の例：「次の 3 ゲームウィークで 700 万ポンド以下のベストミッドフィールダーは？」、 「チーム 1234567 の移籍案を提案して」、「今週 Bench Boost を使うべき？」

セットアップ

Python 3.12 以降が必要です。

git clone https://github.com/GilbertKamau/fpl_mcp.git && cd fpl_mcp
python -m venv .venv
# Windows: .venv\Scripts\activate     macOS/Linux: source .venv/bin/activate
pip install -e ".[supabase,dev]"
fpl-sync all       # load data (~3 min to SQLite; ~15 min to a remote Supabase the first time)
fpl-model all      # train the model and write predictions (~3-6 min the first time)

fpl-sync のジョブ：

ジョブ	内容	時間
live	選手、価格、負傷情報、チーム、ゲームウィーク、試合日程	数秒
current	今シーズンの全選手の試合ごとの統計（FPL API）	約 1 分
history	vaastav から過去シーズンを取得（特定のシーズンを選ぶ場合は --seasons 2024-25）	数分、一度のみ
all	上記すべて
weekly	live + current を実行後、再トレーニングして予測を更新	約 5 分

fpl-model のジョブ：evaluate（テストのみ）、compare（特徴セットを並べて比較）、train、predict、all（トレーニング + 予測）。 履歴を再読み込みした後、--refresh-cache を追加すると、過去シーズンのローカルキャッシュが再構築されます。

データベース

デフォルトでは SQLite を data/fpl.db に保存します。Supabase を使うには、.env.example を .env にコピーし、 Supabase の Session pooler 接続文字列を DATABASE_URL として貼り付けます（直接の db.<ref>.supabase.co ホストは IPv6 のみ対応です）。パスワード内の特殊文字は自動的にエンコードされます。 テーブルは自動的に作成されます。

テーブル	内容
players、teams、gameweeks、fixtures	今シーズンのスナップショット
player_gameweeks	全シーズンにおける選手ごとの試合ごとに 1 行。player_code でシーズンをまたいで選手を紐付けます
season_teams	各シーズンのチーム ID → 名前
predictions	今後の各試合における選手ごとの予想ポイント
prediction_history	ライブスコアリング用に、ベンチマークとともに記録されたすべての予測
model_artifacts	トレーニング済みモデル
model_runs	各トレーニング実行、そのテスト結果、採用されたかどうか
sync_log	各同期の実行時刻

データに関する注意点：2019-20 シーズンのゲームウィークは 47 まであります（COVID による再開後は 39-47 として採番されています）。 2024-25 には AM（アシスタントマネージャー）の行が含まれますが、モデルは無視します。xG/xA は 2022-23 以降に存在します。

data/（SQLite バックアップ、キャッシュ、ログ）、models/、.env は Git の追跡対象外で、ローカルの pre-commit フックによってコミットが拒否されます。

予測モデル

LightGBM は、キックオフ前に入手可能な情報から、各選手の試合ごとのポイントを予測します。

• 調子： 直近1、3、6、12、38試合の移動平均（ポイント、出場時間、先発出場数、xG、xA、ボーナス、BPS、ICT、守備貢献など）
• 市場： そのゲームウィークの保有率と純移籍数をパーセンタイルで表したもの（選手のコンディションと調子に関するファンの見方）
• 状況： 価格、ポジション、ホーム／アウェイ、前回の試合からの日数
• チーム力： 両クラブの最近の得点数と、攻撃時・守備時の xG

ゲームウィークの予想ポイントは各試合の合計です。そのため、ダブルゲームウィークでは2試合分として計算されます。 負傷と出場停止に関する情報に基づき、FPL の出場可能性を使って次のゲームウィークの予測を調整します。 学習済みモデルはデータベースに保存されるため、どのマシンでも使って予測できます。

過去のシーズンでのテスト。 ウォークフォワード方式です。直近3つの完了済みシーズンそれぞれについて、モデルはそれ以前のシーズンのみで学習し、すべての試合を予測します。ベースラインは、選手の直近6試合の平均ポイントです。

シーズン	モデルの MAE	ベースラインの MAE	レギュラー出場選手：モデル／ベースライン
2023-24	0.931	0.999	2.19 / 2.40
2024-25	0.988	1.053	2.20 / 2.41
2025-26	0.954	1.055	2.26 / 2.55

全体でベースラインを7.5％上回っています。直近の試合の調子、シーズンを通じた調子、市場の特徴量を加えたことで、平均 MAE は0.982から0.958に改善し、すべてのテストシーズンで精度が向上しました（fpl-model compare で再実行できます）。再学習したモデルを使用するのは、ベースラインを上回り、現在のモデルより悪くない場合に限られます。

過去シーズンのテストには負傷情報がありません（過去の記録がないため）。そのため、実運用時の精度は実際より低く見積もられます。また、FPL 独自の予想ポイントと公平に比較することもできません。過去の xP 列には負傷情報が含まれており、2025-26 の値は別の尺度で表されています。

実運用での追跡。 すべての予測がアーカイブされます。各ゲームウィーク終了後、締め切り前に行った予測を実際のポイントと照合し、同じ時点で記録された2つのベンチマーク、すなわち6試合ベースラインと FPL 独自の予想ポイント（ep_next）と比較します。また、各手法で上位20人の選手が実際に獲得したポイントも比較します。model_report で継続的な結果を確認できます。

FPL のポイントは非常に変動が大きく、同じパフォーマンスから2ポイントと15ポイントのどちらも生じる可能性があります。そのため、予測は推定値として扱ってください。

オプティマイザー

HiGHS（PuLP 経由）で解く整数計画法により、FPL のルールに従います。GK 2人／DF 5人／MF 5人／FW 3人、各クラブから最大3人、有効なフォーメーション、予算、そして無料移籍数を超える移籍1回につき −4 ポイントを考慮します。予測の信頼性は先のゲームウィークほど低くなるため、後のゲームウィークのポイントは週ごとに割り引かれます（×0.85）。

マネージャーのチームには、公開エンドポイントのみを使用します（ログイン不要）。売却価格はマネージャーの移籍履歴から推定します（FPL では価格上昇分の半額が保持されます）。無料移籍数はゲームウィークの履歴から取得します（最大5回まで繰り越し可能で、ワイルドカードとフリーヒットの週も保持されます）。前回の締め切り後に行われた移籍はまだ公開されていないため、含まれません。

MCP ツール

ツール	機能
gameweek_status	現在／次のゲームウィークと締め切り
search_players	ポジション、チーム、価格、出場時間で絞り込み、任意のスタッツで並べ替え
get_player	スタッツ、負傷情報、直近6試合、次の5ゲームウィークの試合日程
compare_players	2～6人の選手を、90分あたりの数値や価値の数値とともに並べて比較
get_fixtures	チームの次の試合日程、またはゲームウィーク全体
team_summary	結果、ゴール、クリーンシート、試合日程、主力選手
player_season_history	2016-17シーズン以降の各シーズンにおける選手の合計値
get_my_team	チーム ID を指定して任意のマネージャーのスカッドを取得（公開情報、ログイン不要）
predict_points	次の1～5ゲームウィークの予想ポイントを順位付けして表示
model_report	ベースラインと比較したモデルの精度
optimal_squad	予算に応じて、一から最適な15人のスカッドを作成
suggest_transfers	チームに最適な移籍案、または移籍を見送るためのアドバイス
pick_captain	キャプテン、副キャプテン、上位5人の候補
chip_advice	今期に残っているチップ、それぞれの価値、使用するか温存するか
refresh_data	最新のスナップショットを再取得

AI クライアントへの接続

サーバーの実行方法は2つあります。

• ローカル（stdio）： AI アプリがコンピューター上でサーバーを起動します。Claude Code、 Claude Desktop、Cursor、VS Code で動作します。インターネットには公開されません。
• リモート（HTTP）： サーバーを公開 HTTPS URL でホストします（デプロイを参照）。 コンピューター上でプログラムを起動できない claude.ai、ChatGPT、Grok では、この方法が必要です。

例では、/path/to/fpl_mcp/.venv/bin/python は仮想環境内の Python を指します （Windows の場合：C:\path\to\fpl_mcp\.venv\Scripts\python.exe）。また、 https://your-server.example.com/mcp はデプロイした URL を指します。

Claude Code

claude mcp add fpl -- /path/to/fpl_mcp/.venv/bin/python -m fpl_mcp.server        # local
claude mcp add --transport http fpl https://your-server.example.com/mcp          # remote

Claude Desktop

ローカル：Settings > Developer > Edit Config の順に選択し、claude_desktop_config.json に追加します。

{
  "mcpServers": {
    "fpl": { "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] }
  }
}

リモート：Settings > Connectors > Add custom connector を使用します（下記の claude.ai と同じです）。

claude.ai

Settings > Connectors > Add custom connector の順に選択し、https://your-server.example.com/mcp を貼り付けます。 有料プランで利用できます。Team／Enterprise では、オーナーが組織に追加します。claude.ai はログインなし、または OAuth を使用するサーバーに接続するため、MCP_AUTH_TOKEN は設定しないでください。

ChatGPT

Developer mode（Settings > Apps & Connectors > Advanced）を有効にし、URL https://your-server.example.com/mcp を指定して認証方式を None にしたコネクターを作成し、チャットのツール メニューから選択します。利用できるプランは異なるため、OpenAI の最新ドキュメントを確認してください。claude.ai と同様に固定トークンを 送信できないため、MCP_AUTH_TOKEN は設定しないでください。

Grok（xAI API）

Grok は xAI API を通じてリモート MCP サーバーに接続します。

from xai_sdk import Client
from xai_sdk.chat import user
from xai_sdk.tools import mcp

client = Client()  # reads XAI_API_KEY
chat = client.chat.create(
    model="grok-4.7",
    tools=[mcp(server_url="https://your-server.example.com/mcp", server_label="fpl")],
)
chat.append(user("Who should I captain in gameweek 7?"))
print(chat.sample().content)

または Responses API を使用する場合は、これを tools に追加します。

{ "type": "mcp", "server_url": "https://your-server.example.com/mcp", "server_label": "fpl" }

MCP_AUTH_TOKEN を設定した場合は、"authorization": "<token>" も渡してください。

Cursor

~/.cursor/mcp.json（すべてのプロジェクト）または .cursor/mcp.json（1つのプロジェクト）に追加します。

{
  "mcpServers": {
    "fpl": { "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] }
  }
}

リモートの場合は、"fpl": { "url": "https://your-server.example.com/mcp" } を指定します。トークンを設定した場合は、 "headers": { "Authorization": "Bearer <token>" } も追加します。

VS Code（GitHub Copilot エージェントモード）

.vscode/mcp.json：

{
  "servers": {
    "fpl": { "type": "stdio", "command": "/path/to/fpl_mcp/.venv/bin/python", "args": ["-m", "fpl_mcp.server"] }
  }
}

リモートの場合は、"fpl": { "type": "http", "url": "https://your-server.example.com/mcp" } を指定します。

その他

stdio または Streamable HTTP に対応する MCP クライアントであれば、どれでも動作します。サーバーを対話形式で試すには、 npx @modelcontextprotocol/inspector /path/to/fpl_mcp/.venv/bin/python -m fpl_mcp.server を実行します。

デプロイ

ホスト型サーバーはデータベースを読み取るだけです。データ処理、学習、予測はお使いのマシン（または任意のスケジュールジョブ）で fpl-sync weekly を実行し、ホスト型サーバーは10分以内に新しい予測を取り込みます。そのため、Supabase など、両方からアクセスできるデータベースが必要です。

1. パブリックサーバー用の読み取り専用データベースユーザーを作成します。 Supabase の SQL エディターで scripts/supabase_readonly_role.sql を実行します。

2. デプロイします。 Render では、New > Blueprint を選び、このリポジトリのフォークを指定すると、render.yaml がセットアップを行います。それ以外の環境（Fly.io、Railway、Google Cloud Run、VPS）では、Dockerfile を使用します。

3. 環境変数を設定します。

   変数	必須	目的
   DATABASE_URL	はい	読み取り専用ユーザー用の Supabase Session pooler URI
   MCP_AUTH_TOKEN	いいえ	設定すると、すべてのリクエストに Authorization: Bearer <token> が必要です。Grok、Cursor、VS Code は送信できますが、claude.ai と ChatGPT は送信できません
   FPL_MCP_ALLOW_REFRESH	いいえ	1 を設定すると、refresh_data ツールが公開されます（ホスト環境ではデフォルトで無効）
   PORT	いいえ	ほとんどのホストで自動設定されます。デフォルトは8000です

4. MCP URL は https://<your-app>/mcp です。https://<your-app>/health は {"status":"ok"} を返します。

HTTP サーバーをローカルで実行するには、fpl-mcp --http を実行します（http://127.0.0.1:8000/mcp で提供されます）。

トークンがなければ、URLを知っている人なら誰でもツールを呼び出せます。データは公開されている FPL データで、サーバーは読み取り専用ですが、URLが広く共有された場合は、トークンを設定するか、ホストのアクセス制御で保護してください。

定期更新

GitHub Actions が共有データベースを最新の状態に保ちます。

実行日時（UTC）	モード	処理内容
火曜日 06:00	weekly	データと結果を更新し、再学習して予測
金曜日 06:00	news	価格と負傷ニュースを更新して予測

Actions タブから手動で実行できます（Scheduled update > Run workflow）。書き込み権限のある DATABASE_URL のリポジトリシークレットが必要で、フォークではなくメインリポジトリでのみ実行されます。独自のコピーを実行するには、フォークにシークレットを追加し、ワークフローの if: 行を変更してください。

GitHub Actions を使わない場合は、cron または Windows タスク スケジューラから fpl-sync weekly（または fpl-sync live + fpl-model predict）を実行してください。Windows では scripts\update.ps1 が両方のモードを実行し、data\logs にログを記録します。

テスト

.venv\Scripts\python -m pytest

ロードマップ

1. データパイプライン（FPL API + vaastav → SQLite/Supabase）
2. 読み取り専用 MCP ツール
3. ポイント予測：ローリング平均ベースラインに対するウォークフォワード検証を用いた LightGBM（FPL 独自の予想ポイントとのライブ追跡も）
4. オプティマイザー：最適なチーム編成、移籍、キャプテン、チップのアドバイス
5. GitHub Actions での定期更新（同期 → 再学習 → 予測）
6. claude.ai、ChatGPT、Grok、その他のリモートクライアント向けの HTTP ホスティング
7. 任意：FPL チームへの変更適用（デフォルトではプレビューのみ）

貢献

Issue とプルリクエストを歓迎します。PR を提出する前に pytest を実行し、.env、data/、models/ は絶対にコミットしないでください。貢献を提出することで、本プロジェクトの MIT License に基づいてライセンスされることに同意したものとみなされます。

ライセンス

Copyright (c) 2026 Gilbert Kamau. MIT License に基づいて公開されています。著作権表示とライセンス表示を保持する限り、商用利用を含め、コードの使用、複製、変更、配布が可能です。サードパーティのソフトウェアとデータについては、THIRD_PARTY_NOTICES.md に記載しています。

クレジットと免責事項

過去のデータは vaastav/Fantasy-Premier-League（MIT License に基づくコード）から、ライブデータは公開されている FPL API から取得しています。Fantasy Premier League のデータは Premier League の所有物です。MIT License が適用されるのは本プロジェクトのコードのみで、データには適用されません。本プロジェクトは Premier League または Fantasy Premier League と提携しておらず、承認も受けていません。FPL API は責任を持って利用し、予測は保証ではなく推定値として扱ってください。