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-mcpSet 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 |
| Supported competitions, season metadata, data source and licence per competition |
| Free-text team/competition name → stable IDs |
| Fixtures and results, filtered by date / competition / team / status / season / round, cursor-paginated |
| Standings table for a competition and season |
| Starting XI, bench, formation |
| Goals, cards, substitutions, commentary timeline |
| One entry per shot: pitch coordinates + xG value |
| Derived context — form, head-to-head, pre-computed signals |
| League xG table: xG for, xG against, over/under-performance vs actual goals |
| Bookmaker benchmark + implied fair probabilities. Informational, not betting advice |
| Remaining monthly quota — this call does not consume quota |
| 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_limiterror 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 healthnpm 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 toolsfootballstack_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_searchSearch teams and competitionsA
Resolve a free-text team or competition name into stable FootballStack IDs. Use this before any tool that takes a competition or team, instead of guessing an ID.
Inputs: q (required).
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
Scored across 12 tools
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.
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.
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.
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
Hosted MCP server for live public-data APIs and Skills for AI agents.
MCP server for your apps' tools and custom tools, plus hosted AI agents and approval-gated workflows
MCP server providing access to the Scorecard API to evaluate and optimize LLM systems.
Financial data MCP server for Claude, ChatGPT, Cursor and Codex. Real-time stock quotes, financial statements, options flow, SEC filings, insider trades, 13F holdings, macro data and market news from gloom.sh, the open-source Bloomberg Terminal alternative.
Related MCP Servers
- AlicenseBqualityDmaintenanceMCP-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.2937 PyPIMIT
- AlicenseNot gradedqualityDmaintenanceAn MCP server that enables LLMs to act as World Cup forecasting agents, pulling live odds, getting model forecasts, and simulating tournament brackets via natural language.MIT
- FlicenseNot gradedqualityDmaintenanceMCP 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.-
- AlicenseAqualityCmaintenanceMCP server that gives Claude live access to Major League Soccer data — teams, matches, standings, rosters, and schedule-strength analytics — via the ESPN public API.11MIT