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.

FutPicks