FutPicks

FutPicks MCP Server

Model Context Protocol server for football data: probable lineups with a per-player start probability and expected fantasy points, match analysis, model picks and a public track record — LaLiga, Premier League, Serie A, Bundesliga, Ligue 1 and Primeira Liga.

Every tool calls the public futpicks.com REST API over HTTPS. No database access, no shell, no local secrets beyond the API tokens you put in the environment. The lineup, match and track-record tools need no key at all.

The lineups are graded in public against the confirmed XI, so the accuracy the tools report is measured, not claimed. Same data as futpicks.com/onces/la-liga.

Quick start

Add it to any MCP client (Claude Code shown here) — no install step, npx fetches it:

{
  "mcpServers": {
    "futpicks": {
      "command": "npx",
      "args": ["-y", "futpicks-mcp"]
    }
  }
}

Then ask for a probable lineup: flab_teams to find a club, flab_matches_upcoming for the fixtures, flab_match_details for the projected XI and the model's read of the match.

To unlock the Pro and admin tools, add the keys:

{
  "mcpServers": {
    "futpicks": {
      "command": "npx",
      "args": ["-y", "futpicks-mcp"],
      "env": {
        "FUTPICKS_API_KEY": "flab_live_…"
      }
    }
  }
}

Building from source

git clone https://github.com/Khavel/futpicks-mcp.git
cd futpicks-mcp
npm install
npm run build      # compiles src/index.ts → dist/index.js

For local development with hot reload: npm run dev.

Environment variables

Variable	Required for	Description
FUTPICKS_API_URL	No	API base URL (default: https://futpicks.com)
FUTPICKS_API_KEY	Data tools	Data-scope API key (ProTier policy)
FUTPICKS_OPS_TOKEN	Ops tools	Ops-scope API key (Admin policy, admin only)

Public tools work with no token at all.

Where to get the tokens

Mint API keys from the web app: futpicks.com → Account → API Keys (Cuenta → Claves de API).

• FUTPICKS_API_KEY — create a Data-scope key. It looks like flab_live_… and satisfies the Pro-tier (ProTier) endpoints. Pro and admin users can mint these.
• FUTPICKS_OPS_TOKEN — create an Ops-scope key. It looks like flab_ops_… and satisfies the admin (Ops) endpoints. Only admins can mint these.

The raw key is shown once at creation, so copy it into your environment immediately. Keys are stored only as SHA-256 hashes, support optional expiry, and can be revoked from the same screen; revoked or expired keys are rejected with 401.

Tools

Public (no auth)

Tool	Endpoint	Key params
flab_picks_today	GET /api/picks/today	date?, rating?, market?
flab_pick_details	GET /api/picks/{id}	id
flab_picks_board	GET /api/picks/board	date?, league?, market?, rating?, odds/edge ranges
flab_matches_today	GET /api/matches/today	—
flab_match_details	GET /api/matches/{id}[/intelligence]	id, includeIntelligence?
flab_matches_upcoming	GET /api/matches/upcoming	days? (1–30)
flab_teams	GET /api/teams	—
flab_track_record	GET /api/track-record/filtered	market?, league?, rating?, outcome?, from?, to?
flab_health	GET /api/health	—

Data tools (require FUTPICKS_API_KEY)

Tool	Endpoint	Key params
flab_picks_history	GET /api/picks/history	from?, to?, league?, market?, rating?, page?, pageSize?
flab_evaluate_matches	GET /api/evaluate/matches	—
flab_evaluate_match	GET /api/evaluate/{matchId}	matchId
flab_backtest_run	POST /api/backtest/run	dateFrom, dateTo, rating?, market?, minEdge?, leagueId?
flab_export_picks	GET /api/picks/export	from?, to?, market?, rating? (returns CSV)
flab_data_catalog	GET /api/v1/data	—

Ops tools (require FUTPICKS_OPS_TOKEN, admin-only)

Tool	Endpoint	Key params
flab_ops_run	POST /api/v1/ops/operations/{kind}	kind, plus date?/lastDays?/windowDays?/matchId?
flab_ops_status	GET /api/v1/ops/operations/{id}[/result]	id, includeResult?

flab_ops_run kinds: ingestion-runs, scoring-runs, settlement-runs, calibration-runs, intelligence-refreshes. The server auto-generates an Idempotency-Key per ops POST.

Claude Desktop configuration

Add to claude_desktop_config.json:

{
  "mcpServers": {
    "footballlab": {
      "command": "node",
      "args": ["C:/Users/ceja_/Desktop/Desarrollos/Furbov2/mcp-server/dist/index.js"],
      "env": {
        "FUTPICKS_API_URL": "https://futpicks.com",
        "FUTPICKS_API_KEY": "your-pro-tier-token",
        "FUTPICKS_OPS_TOKEN": "your-admin-token"
      }
    }
  }
}

Verify locally

npx @modelcontextprotocol/inspector node dist/index.js

Then call flab_health (no token needed) — it should return live system status.

Security

• No tool reads DB connection strings, appsettings secrets, or shells into the VPS.
• All inputs are validated with zod; page sizes and ranges are capped server-side.
• Tokens are read from environment variables only and never logged.
• Data/ops tools fail with a clear message when their token is missing — they never fall back to an unauthenticated call.
• Ops mutations send a fresh Idempotency-Key so retries are deduplicated by the API.