fpl-strategy-mcp

A custom Fantasy Premier League MCP server, built specifically to operationalize our squad-building framework — not a generic player-lookup tool. Every tool maps to a named section of the strategy documents this project is built on:

No FPL email or password is ever required. Everything reads public, unauthenticated endpoints only — this was a deliberate choice, partly because we don't need anything else, and partly because handing real login credentials to any third-party code (ours included) is a reasonable thing to be cautious about.

Reliability notes (read this if tools "randomly" fail)

The server runs in stateless streamable-HTTP mode (stateless_http=True). The SDK default is stateful, which keeps MCP sessions in process memory — on a free-tier host that sleeps and restarts, the client's stored session id is invalidated on every restart and every tool call fails with a generic execution error until the connector is re-initialised. Stateless mode makes each call self-contained, so a restart is just a slow first call, not a broken session.

Other things done deliberately:

• One shared process-wide cache (fpl_client.SHARED_CACHE), so the multi-MB bootstrap-static payload is downloaded once per 4 hours, not once per call.

• 30s timeout with retries on timeouts and 5xx; 403s are reported as "the host is being blocked", which is the FPL API's usual behaviour toward some cloud IPs.

• GET /health for Render's health check and for a keep-alive pinger. Pointing a free cron (e.g. cron-job.org, every 10 min) at /health stops the free tier spinning down between calls.

If a tool still fails: call fpl_ping. If it reports ok: true, the problem is in the tool; if not, its error field says whether it's the API or the host.

Related MCP server: FPL MCP Server

What's been verified vs. what to check on first run

Built and tested in a sandboxed environment with no access to the live FPL API (network allowlist restriction) — so testing here meant:

• Full unit tests against synthetic data shaped like real FPL API responses (test_analysis.py) — 18/18 passing.

• Full integration tests through the actual MCP tool-call path with a mocked API layer (test_server_integration.py) — 19/19 passing, including the get_team happy path, the stateless-mode diagnostics tool, and the shared cache.

• Syntax and import verification for every file.

The one thing that's genuinely unverified against the real API is the exact field names for defensive-contribution stats — that's the newest, least publicly documented part of the FPL API. Run this once, after setup, before trusting the DEFCON numbers for real decisions:

python check_live_api.py

It tells you plainly whether the field-name guesses in analysis.py matched reality, and exactly what to edit if they didn't. If a field name is wrong, the tool fails loudly with the actual available keys listed — it will never silently return a wrong number.

Setup — Option A: Claude Desktop or Claude Code (recommended, simplest)

This runs entirely on your own machine. Nothing is exposed to the internet, nothing needs hosting, and it's the standard way MCP servers are used locally.

1. Install Python 3.10+ if you don't have it.

2. In this folder, install dependencies:

   pip install -r requirements.txt

3. Run the live field-name check once:

   python check_live_api.py

4. Add this to your Claude Desktop config file (macOS: ~/Library/Application Support/Claude/claude_desktop_config.json, Windows: %APPDATA%\Claude\claude_desktop_config.json):

   {
     "mcpServers": {
       "fpl-strategy": {
         "command": "python",
         "args": ["/full/path/to/fpl-strategy-mcp/server.py"]
       }
     }
   }

   Use the full absolute path to server.py — relative paths cause silent failures.

5. Restart Claude Desktop completely. You should see the FPL tools available in the tools/hammer icon.

Claude Code works the same way — add the equivalent entry to its MCP config.

Setup — Option B: remote, for use directly inside claude.ai web chat

This chat interface (claude.ai) only connects to MCP servers that are reachable over the public internet — it cannot reach a server sitting on your laptop. To use these tools directly in a claude.ai conversation (rather than Claude Desktop/Code), you'd need to:

1. Deploy this server somewhere publicly reachable, using HTTP transport instead of stdio. Change the last line of server.py to:

   mcp.run(transport="streamable-http", port=8000)

   (Small free-tier hosts work fine for this — Render, Railway, Fly.io, etc.)

2. In claude.ai: Settings → Connectors → Add custom connector, and paste your server's public URL.

This is more setup than Option A for the same result, so start with Option A unless you specifically need it inside this exact chat interface.

Files

• server.py — tool registrations (the MCP-facing layer)

• fpl_client.py — shared API client with caching, no business logic

• analysis.py — our custom calculations (DEFCON hit-rate, rolling fixtures, tier classification, hit-math) — this is the part that's genuinely ours

• check_live_api.py — one-time live field-name verification

• test_analysis.py, test_server_integration.py — the test suite; re-run either with python test_analysis.py any time you change analysis.py

A note on trust

You mentioned not trusting pre-built MCPs for this — that's a reasonable instinct, especially given at least one public FPL MCP server asks for your real FPL email and password to unlock team-viewing features. This server never asks for that, and every file is short enough to read end to end. That's the actual point of building our own: not that public ones are malicious, but that you shouldn't have to take it on faith.