Skip to main content
Glama
footballstack-mcp

footballstack-mcp

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

Tool

What it returns

footballstack_competitions

Supported competitions, season metadata, data source and licence per competition

footballstack_search

Free-text team/competition name → stable IDs

footballstack_matches

Fixtures and results, filtered by date / competition / team / status / season / round, cursor-paginated

footballstack_standings

Standings table for a competition and season

footballstack_match_lineups

Starting XI, bench, formation

footballstack_match_events

Goals, cards, substitutions, commentary timeline

footballstack_match_xg

One entry per shot: pitch coordinates + xG value

footballstack_match_context

Derived context — form, head-to-head, pre-computed signals

footballstack_league_xg

League xG table: xG for, xG against, over/under-performance vs actual goals

footballstack_odds

Bookmaker benchmark + implied fair probabilities. Informational, not betting advice

footballstack_quota

Remaining monthly quota — this call does not consume quota

footballstack_health

Reachability check. Works without an API key

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.

Available Tools

12 tools
footballstack_competitionsList competitionsA

List the competitions FootballStack supports, with season metadata and the data source/licence per competition. Call this first: the catalogue is broader (75 competitions) than the deep coverage. Deepest: Bundesliga, 2. Bundesliga, DFB Pokal, Superliga României. Historical/analytics only for Premier League, La Liga, Serie A, Ligue 1.

Inputs: no named parameters.

footballstack_healthCheck API healthA

Check that the API is reachable. Works without an API key — use it to verify the server is wired up correctly.

Inputs: no named parameters.

footballstack_league_xgGet league xG tableA

League-wide xG and performance table: xG for, xG against and over/under-performance versus actual goals. The right tool for 'is this team overperforming?' questions.

Inputs: league.

footballstack_match_contextGet derived match contextB

Derived context for one match — form, head-to-head and related pre-computed signals.

Inputs: id (required).

footballstack_matchesList fixtures and resultsA

List fixtures and results, filtered by date, competition, team, status, season or round. Paginated via cursor. Use the IDs returned here as the match id for the lineups, events, xg and context tools.

Inputs: date, team, limit, round, +4 more.

footballstack_match_eventsGet match eventsA

Key events and commentary timeline for one match (goals, cards, substitutions). For live matches this is the polling-heavy endpoint — mind the monthly quota.

Inputs: id (required).

footballstack_match_lineupsGet lineupsC

Starting XI, bench and tactical formation for one match. Requires a paid plan on most competitions.

Inputs: id (required).

footballstack_match_xgGet shot map and xGA

Shot-level Expected Goals for one match: one entry per shot with pitch coordinates and xG value, i.e. everything needed to draw a shot map or model finishing quality.

Inputs: id (required).

footballstack_oddsGet odds and fair probabilitiesB

Bookmaker odds benchmark and model-derived implied fair probabilities for one match. Informational only — not betting advice.

Inputs: matchId (required).

footballstack_quotaCheck remaining quotaA

Inspect the monthly request quota without consuming a request. Call this when a tool returns quota_or_rate_limit.

Inputs: no named parameters.

footballstack_standingsGet league standingsB

Standings table for one competition, optionally for a specific season.

Inputs: competition (required), season.

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    A3.7/5.0

    Scored across 12 tools

    Disambiguation5/5

    Each tool serves a clearly distinct purpose: listing competitions, resolving names, fetching matches, standings, lineups, events, xG (match and league level), context, odds, quota, and health checks. No two tools overlap in functionality, and descriptions make the boundary obvious.

    Naming Consistency4/5

    All tools share the 'footballstack_' prefix and use snake_case, but a mix of noun and verb stems (e.g., footballstack_competitions vs footballstack_search) creates a minor inconsistency. The pattern is still predictable and readable overall.

    Tool Count5/5

    12 tools is a well-scoped set for a football data API, covering listing, search, match data, standings, analytics, and operational concerns (quota, health). Each tool contributes meaningfully without bloating the surface.

    Completeness4/5

    The server covers core football data needs: competitions, matches, standings, lineups, events, xG, odds, and context. Minor gaps exist (e.g., no dedicated team/player stats endpoint), but the documented scope—match results, analytics, and derived signals—is well covered with no dead ends.

    Related MCP Connectors

    Related MCP Servers

    • A
      license
      B
      quality
      D
      maintenance
      MCP-compatible server that gives AI agents access to alternative sports data across 30+ leagues — odds, events, probabilities, settlement, and futures for prediction markets, DFS platforms, and sportsbooks.
      29
      37 PyPI
      MIT
    • F
      license
      Not graded
      quality
      D
      maintenance
      MCP server for a World Cup 2026 prediction game assistant, providing tools for live game data via PostgreSQL and semantic search over football articles via RAG.
      -
    • A
      license
      A
      quality
      C
      maintenance
      MCP server that gives Claude live access to Major League Soccer data — teams, matches, standings, rosters, and schedule-strength analytics — via the ESPN public API.
      11
      MIT