footballstack-mcp

MCP server for the FootballStack football data API. Gives an LLM client real football data — fixtures, standings, lineups, live events, shot-level xG with pitch coordinates, and model-derived fair odds — instead of a hallucinated scoreline.

12 tools, 1 prompt. Node ≥ 20, no build step.

Install

npx footballstack-mcp

Set your API key in the environment. Free tier: 1,000 requests/month. Get a key at footballstackapi.com/sign-in.

Claude Desktop / Claude Code

{
  "mcpServers": {
    "footballstack": {
      "command": "npx",
      "args": ["-y", "footballstack-mcp"],
      "env": { "FOOTBALLSTACK_API_KEY": "fs_live_..." }
    }
  }
}

Cursor / Windsurf / any stdio MCP client

Same block, in that client's MCP config file.

Related MCP server: worldcup-ai-forecaster

Tools

Prompt: scout_team_form — resolve a team, pull its last 5 matches, read the xG behind the results.

Start with footballstack_search to resolve IDs. Guessing IDs wastes quota: 404s and empty results are metered like any other request.

Coverage, stated honestly

The catalogue lists 75 competitions. Depth is not uniform, and the catalogue is wider than the deep coverage.

• Deepest: Bundesliga, 2. Bundesliga, DFB Pokal, Superliga României

• Expanded European: Eredivisie, Primeira Liga, Süper Lig, Pro League, Scottish Premiership

• Historical / analytics only: Premier League, La Liga, Serie A, Ligue 1 (xG is Understat-derived)

Call footballstack_competitions and check your league before you build on it.

Quota behaviour

• Free: 1,000 requests/month, 10 req/min. Developer $9/month: 10,000 requests/month, 60 req/min, includes xG, shot maps, lineups, live events and fair odds. Pro $29/month: 50,000/month, 180 req/min.

• No overage billing. When the quota is spent the API returns 429; this server surfaces that as a quota_or_rate_limit error rather than an empty result.

• Quota resets on the 1st of the month, UTC.

• Every request is metered, including 404s and empty results.

When this is the wrong tool

• High-frequency live polling across many competitions. A monthly quota is the wrong shape for it — a per-day or per-second plan elsewhere will cost you less.

• Leagues outside the deep-coverage list above.

• You need a contractual SLA, uptime credits or a named support contact. Not offered at these prices.

Development

npm install
npm run smoke   # boots the server over stdio, lists tools, calls health

npm run smoke works without an API key: footballstack_health returns live status, and a key-gated tool returns a readable missing_api_key error so you can tell "not configured" from "broken".

MIT.