Fantasy Premier League

Fantasy Premier League MCP

あらゆるMCP対応エージェントで利用できる、Fantasy Premier League用のMCPサーバーです。 チーム編成や統計の確認、選手のランキング、差別化候補の検討、チームの変更ができます。公式MCP Registryに公開されており、stdioまたはリモートのストリーミングHTTP経由で動作します。

このプロジェクトは、無関係な別プロジェクトがすでに所有しているfpl-mcpではなく、fantasy-premier-league-mcpとしてPyPIにパッケージされています。

インストール

uvを使ってインストールします（推奨）：

uv tool install fantasy-premier-league-mcp

または、インストールせずに実行します：

uvx fantasy-premier-league-mcp

fpl_loginにはローカルのChromiumのインストールも必要です。一度だけ、次のコマンドでインストールしてください：

uvx --from playwright playwright install chromium

開発環境を用意するには、仮想環境を作成し、プロジェクトをインストールします：

uv sync --group dev
uv run playwright install chromium

リリース

一致するバージョンタグがプッシュされると、GitHub Actionsによってリリースが公開されます。 ワークフローでパッケージをテストしてビルドし、Trusted Publishingを使ってPyPIに公開した後、一致するserver.jsonを公式MCP Registryに公開します。PyPI APIトークンはGitHubに保存されません。

最初のリリースの前に、次の内容でPyPIの保留中のTrusted Publisherを設定してください：

• owner：anubabajide
• repository：fpl-mcp
• workflow：release.yml
• environment：pypi
• PyPI project：fantasy-premier-league-mcp

pypiという名前の保護されたGitHub環境を作成します（たとえば、手動承認を必須にします）。この一度限りの設定が完了したら、準備済みのバージョンを次のコマンドで公開します：

git tag v0.3.2
git push origin v0.3.2

Playwrightは、「認証」で説明している一度限りのブラウザーサインインを実行します。

エージェントに接続する

MCP対応クライアントなら、どれでもこのサーバーを利用できます。デフォルトではstdio経由でMCPを使用し、リモートMCPサーバーに対応したエージェント向けに、リモートのストリーミングHTTPコネクターとしても実行できます。

ローカルstdio（推奨）

エージェントの接続先にuvxを指定します：

{
  "mcpServers": {
    "fpl": {
      "command": "uvx",
      "args": ["fantasy-premier-league-mcp"]
    }
  }
}

このブロックをクライアントのMCP設定に使用します。多くのクライアントでは、.mcp.json／.cursor/mcp.jsonファイルを使うか、設定画面から設定できます。最上位のキーにmcpServersではなくserversを使うクライアントもありますが、fplエントリーは同じです。チェックアウト済みのコピーを使う場合は、commandにプロジェクトのPythonを指定し、python -m fpl_mcpを実行します。

stdioモードでは、マシンの外部に何も公開されません。これが最も安全な方法です。

リモートHTTP

HTTPS経由でリモートMCPサーバーに接続するエージェントは、組み込みのHTTPトランスポートを利用できます：

export FPL_MCP_SHARED_SECRET="$(python -c 'import secrets; print(secrets.token_urlsafe(32))')"
python -m fpl_mcp --http

次に、その前段にHTTPSトンネルを配置し（例：cloudflared tunnel --url http://localhost:8000）、カスタムコネクターとして、エージェントに生成されたhttps://…/mcp URLを渡します。

HTTPモードは、FPL_MCP_SHARED_SECRET（16文字以上）が設定されていないと起動しません。 これらのツールでは選手の移籍やラインナップの書き換えができるため、エンドポイントを公開すると、URLを知っている人なら誰でもチームを編集できてしまいます。すべてのリクエストにAuthorization: Bearer <secret>を含める必要があります。それ以外はすべて401になります。コネクターを動作させるには、マシンを起動しておく必要があります。

MCP Bundle

ローカルMCPサーバーをバンドルとしてインストールするアプリでは、fpl.mcpbを利用できます。これは、サーバーとその依存関係、同梱のPythonインタープリター、およびmanifest.jsonを含むzipファイルです。アプリの拡張機能UIからインストールしてください。ビルド、更新、Chromiumの詳細については、MCP Bundleのセットアップに関する注意事項を参照してください。

Registryでの検出

このサーバーは公式MCP Registryにio.github.anubabajide/fplとして登録されているため、Registry対応クライアントから直接見つけてインストールできます。

認証

読み取り専用の機能は、ログインしなくてもすべて利用できます。書き込みツールのうち、次の3つ（fpl_set_lineup、fpl_set_captain、fpl_make_transfers）だけはセッションが必要です。

**一度だけサインインします：**エージェントに fpl_login を実行するよう依頼してください。サーバーが動作しているマシン上のブラウザーウィンドウでFPL独自のサインインページが開き、すぐに処理が戻ります。

1. そのブラウザーウィンドウでサインインします。
2. サーバーがFPLから返されるリダイレクトを受け取り、認証コードを交換して、生成されたセッションを自動的に保存します。fpl_login をもう一度呼び出す必要はありません。

サインインは独立したバックグラウンドタスクとして実行されるため、最初の呼び出しでクライアントが処理を諦めても続行します。ウィンドウでの進行状況が失われることはありません。サインインはご自身で行うため、このサーバーがパスワードを認識することはありません。セッションは ~/.fpl-mcp/credentials.json にリフレッシュトークンとして保存され、読み取れるのはあなただけです。アクセストークンは単一のHTTPSリクエストで更新されます。サインイン後にブラウザーを使うことはありません。セッションの有効期限が切れない限り、トークンについて気にする必要はありません。有効期限が切れると、書き込みツールから fpl_login を再度実行するよう案内されます。fpl_auth_status で、ブラウザーでのサインインが完了したかどうかを確認できます。

ブラウザーウィンドウを開けない場合、fpl_login はステータス awaiting_redirect_url と sign_in_url を返します。そのリンクを任意のブラウザーで開き、サインインした後、移動先のアドレスを redirect_url として fpl_login に貼り付けてください。

fpl_logout はセッションを破棄し、FPL側でも無効化します。fpl_auth_status は現在の状態を報告します。

メールアドレスとパスワードを保存しないのはなぜですか？

FPLのIDプロバイダーが、その方法での認証情報交換を拒否するためです。サイトのOAuthクライアント（FPLアプリのバンドルから読み取った bfcbaf69-aade-4c1b-8f00-c1cb8a193030）では、パスワードグラントが設定されていません。

POST https://account.premierleague.com/as/token
     grant_type=password
  -> 400  unsupported_grant_type: "Invalid grant type: password"

サポートされているフローは、ブラウザーでの認可コード＋PKCEです。また、account.premierleague.com はブラウザー以外のHTTPクライアントを拒否します。そのため、どこかの段階で実際のブラウザーを使う必要があります。この方法なら、FPL独自のページを開いた本物のブラウザーウィンドウで、ご自身がログインできます。このサーバーがFPLの認証情報を保存、読み取り、処理することは一切ありません。認可コードは、メモリ内だけに保持されるPKCE検証子を使って引き換えます。その後に保存されるのはリフレッシュトークンであり、パスワードでもブラウザープロファイルでもありません。

ログイン時に二要素認証やボットチェックが表示された場合は、通常のサインインと同様に、そのウィンドウで完了してください。回避されるものはありません。

フォールバック

fpl_set_token は、ブラウザーの起動ができないマシン向けに、DevToolsから手動で貼り付けたベアラートークンを引き続き受け付けます。このトークンの有効期間は約1時間で、自動更新はできず、サーバーが停止するまでしか保持されません。

ツール

セットアップ

ツール	機能
fpl_setup	チームIDとデフォルトのミニリーグIDを保存します
fpl_login	ブラウザーウィンドウで一度サインインします。セッションは記憶されます
fpl_logout	保存されたセッションを破棄します
fpl_auth_status	セッションを確認し、必要に応じてトークンを更新します
fpl_set_token	トークンを手動で貼り付けます（フォールバック）

自分のチーム

ツール	機能
fpl_my_squad	先発XI、ベンチ、キャプテン、フォーメーション、銀行残高、残りのフリートランスファー数、保有チップ
fpl_season_summary	ポイント、総合順位、ゲームウィーク別の順位、チップ、ヒット、過去のシーズン
fpl_gameweek_report	ゲームウィークの選手ごとの得点（ベンチと自動交代を含む）。速報または確定済みの概要
fpl_best_performers	自分のチームを順位付けし、活躍している選手と足を引っ張っている選手を確認します

選手の調査

ツール	機能
fpl_top_players	ゲーム内の優秀な選手をポジション、クラブ、価格で絞り込み、metric または sort_by で順位付けします
fpl_player	選手1人の詳細：統計、対戦日程、セットプレー、負傷情報
fpl_compare_players	2人以上の選手を並べて比較します
fpl_search_players	名前で検索します
fpl_fixture_ticker	近日の対戦難易度でクラブを順位付けします

一括エクスポート（独自のモデリング用）

ツール	機能
fpl_export_players	選手プールをコンパクトな CSV でエクスポートします。プール全体またはページ指定が可能で、順位付けはされません
fpl_export_fixtures	指定期間内の全試合を、1 試合につきチームごとに 1 行でエクスポートします
fpl_export_gameweek_history	終了したゲームウィークの選手別・ゲームウィーク別統計をエクスポートします

これらは順位付けされた上位 N 件ではなく、データセット全体を返すため、クライアント側で独自の最適化を実行できます。デフォルトは CSV です。同じデータを JSON で返すと、トークン数はおよそ 5 倍になります。

デフォルトの選手エクスポートはコンパクトで、約 22 列のため、ツールの結果に収まります。fields="standard" にすると幅広い最適化用の項目（62 列）が復元され、fields="all" ではすべての生データ列（112 列）が含まれますが、サイズに関する警告が表示されます。ids、position、team、min_minutes、max_price でさらに絞り込むか、offset／limit でページ分割できます。レスポンスには has_more と next_offset が含まれます。

fpl_export_fixtures を選手エクスポートの team_id と結合すると、選手別・ゲームウィーク別の予測を作成できます。空き節やダブルゲームウィークはデータの形から判断できます。あるゲームウィークの行がなければ空き節、2 行あればダブルです。

チームのニュースとラインアップ

ツール	機能
fpl_team_news	クラブごとの監督、新加入選手、退団選手、負傷状況フラグ
fpl_predicted_lineups	公開済みの場合は確定した XI、それ以外の場合は算出した予測

監督の情報は、プレミアリーグ独自の Pulse バックエンドから取得し、FPL がすでに提供している pulse_id フィールドを使って FPL と結合します。この情報は文書化もバージョン管理もされていないため、監督情報の取得に応答がない場合、呼び出しを失敗させず unknown を返します。今シーズン、監督は FPL の対象ではないため、交代の影響はポイントではなく、ローテーション、セットプレーの担当、フォーメーションなどに間接的に現れます。

新加入選手と退団選手には、追加の情報源は必要ありません。FPL の team_join_date は実際の移籍情報フィードであり、news のテキストには退団や期限付き移籍の情報がそのまま含まれています。

予測ラインアップは、どこにもデータとして存在しません。これは編集上の判断です。そのため、fpl_predicted_lineups は次のいずれかを返します。

• source: "confirmed" — リーグがキックオフの約 1 時間前に公開した、実際のチームリストです。
• source: "predicted" — ここで算出したヒューリスティックな予測です。最近の先発出場、出場 1 回あたりの出場時間、出場可能状況、セットプレーの担当、価格に基づいて順位付けされます。各選手には score_breakdown が付くため、重み付けに異論があれば確認できます。

昨シーズンの実績は、率と出場量に分けています。合計出場時間だけでは、「負傷していた」のか「先発選手ではない」のかを区別できないためです。Odegaard は昨シーズン、先発出場は 16 試合のみでしたが、その試合では平均 85 分プレーしており、Rice の 88 分とほぼ同じでした。そのため、合計値だけで評価すると、確実に先発するキャプテン候補が XI から外れていました。現在は先発数よりも先発 1 試合あたりの出場時間を重視しています。これは、コンディションが戻っていることや、チーム内での役割を反映するためです。

新加入選手は、加入直後にはクラブでの出場時間がなく、海外からの加入なら記録自体がどこにもないため、代わりに移籍金で評価します。該当する行には new_signing のフラグが付きます。実績ではなく、情報がない状態で評価されるため、XI に入らなかった選手は new_signings_not_predicted に別途記載されます。順位付けだけでは最下位に落ちて「検討されなかった」ように見えてしまいますが、実際には「評価できない」ためです。

ここでは、新監督の好み、プレシーズンの親善試合、記者会見の内容は把握できません。

差別化選手

ツール	機能
fpl_differentials	両方向の情報を提供します。詳細は以下を参照してください
fpl_league_standings	ミニリーグの順位表と、その中でのあなたの順位

チームの変更（いずれも事前確認が必要）

ツール	機能
fpl_set_captain	XI はそのままに、キャプテンマークを変更します
fpl_set_lineup	XI 全体、ベンチの順序、キャプテン、バイスキャプテンを設定します。ベンチブーストまたはトリプルキャプテンを使用できます
fpl_make_transfers	ワイルドカードまたはフリーヒットを使用するかどうかを指定して、選手を移籍させます

差をつける選手の仕組み

fpl_differentials は、ご要望どおり、次の両方向の情報を返します。

• my_differentials — あなたが保有していて、ライバルの保有者が少ない好調な選手です。これらの選手がポイントを獲得すると、ほかの全員との差を広げられます。
• differentials_against_me — あなたが保有していない一方で、多くのライバルが保有している好調な選手です。これらの選手が大量にポイントを獲得するたびに順位を落とすため、移籍候補のリストとしても使えます。

比較対象は次の2種類から選べます。

scope="global"                          # vs ownership across all ~7m FPL managers
scope="league", league_id=123456        # vs the top N teams in one mini-league

リーグ単位の比較のほうが参考になります。ミニリーグの順位は、世界全体のテンプレートではなく、特定のライバルとの比較で決まるためです。各ライバルの実際のスカッドを取得し、実質保有率も報告します。実質保有率ではキャプテンに指定された選手を2倍として数えるため、ライバル全員がある選手をキャプテンにしている場合、その選手の実質保有率は200%となり、実際の影響度を表します。

low_ownership_max（デフォルトは10%）とhigh_ownership_min（デフォルトは20%）でしきい値を調整し、metric=（total_points、form、value、xgi、points_per_game、ict_index、…）で指標を指定できます。

安全性

すべての書き込みツールは、デフォルトでdry_run=trueで実行されます。これにより変更が検証され、変更後のスカッド、ポイントの減点、変更後の銀行残高、ルール違反の有無を含む完全なプレビューが返されます。実際に送信されることはありません。FPLに変更を送信するには、2回目の呼び出しでdry_run=falseを指定する必要があります。

送信前に、サーバーは変更内容がFPL独自のルールに準拠しているか確認します。

• スカッドの構成（GKP 2人／DEF 5人／MID 5人／FWD 3人）と重複がないこと
• どのクラブからも選手が3人を超えていないこと
• 現在の市場価格ではなく、実際の売却価格を基に銀行残高が十分であること
• フォーメーションが合法で、キャプテンと副キャプテンがそれぞれ1人ずつおり、両方ともスタメンであること
• すべての移籍で同じポジション同士を入れ替えていること
• 控えゴールキーパーが正しいベンチ枠に配置されていること

チェックに失敗した場合、何も送信されず、問題の一覧が返されます。追加移籍のポイント減点は、実際のフリートランスファー残数に基づいて計算されます。ワイルドカードまたはフリーヒットを使用する場合、減点は0になります。

ゲームウィークの締め切り

fpl_my_squadとfpl_export_fixturesはどちらも、FPLのUTC形式と英国現地時間に変換した形式で、次のゲームウィークの締め切りを返します。時刻はFPLのbootstrapにあるdeadline_timeを使用します。

• next_deadline_utc — 例：2026-11-07T11:00:00Z
• next_deadline_uk／next_deadline_uk_display — Europe/Londonで表した同じ時刻

fpl_export_fixturesは、対象期間内の各ゲームウィークについてgameweek_deadlinesも一覧表示します。

変更履歴

0.3.2

• free_transfers／free_transfers_availableが、残りの移籍回数（FPL's limitからすでに行った移籍回数を引いた数）を返すように修正し、付与された上限を残数として扱うのではなく、この値からポイント減点を計算するようにしました。ドライランでは、今週すでに行った移籍も含めて正しい減点を報告するようになりました。
• fpl_set_lineupがchip（bboostまたは3xc）を受け付け、送信後にFPLが使用を確認したかどうかを報告するようになりました。ドライランのフローでベンチブーストとトリプルキャプテンを使用できます。
• fpl_gameweek_reportが、開催中のゲームウィークについて、一貫した概要のpoints、points_on_bench、overall_rankを返すようになりました。確定値とas_ofマーカーも併せて返し、保存済みの履歴とライブの選手行を混在させることがなくなりました。
• fpl_my_squadのchips_availableが、保有中のチップを一覧表示するようになりました。ゲームウィークごとの情報はactive_chipとchips_playable_this_gwで確認できます。
• 移籍、ラインナップ、キャプテンの各ツールで、選手の参照（element id）を使用できるようになりました。
• fpl_top_playersで、metricの別名としてsort_byを受け付けるようになりました。
• fpl_export_playersがデフォルトでコンパクトなフィールドセットを返し、ツール結果の制限内に収まるよう、ids、offset、limitを追加しました。
• 新機能：ゲームウィークの締め切り（next_deadline_utc、英国現地時間）がfpl_my_squadとfpl_export_fixturesから返されるようになりました。

プレシーズンに関する注意

第1節のスコアが確定するまで、FPL APIはすべての選手について昨シーズンの合計値を返し続けます。ポイント、出場時間、ゴール、価格はいずれも前シーズンの内容を示し、formは全員が0.00となります。数値が今シーズンの調子として読み取られないよう、ツールはこれをcaveatフィールドで示します。昇格したクラブや新加入選手には、履歴がありません。

またFPLは最初の締切を過ぎるまで誰のチームも公開しないため、それまではfpl_my_squadとfpl_differentialsで自分のドラフトチームを読み取るには、サインイン済みのセッションが必要です。ミニリーグの順位表も空です。