Provides an AI client with real-time football data including fixtures, standings, lineups, live events, and shot-level xG across 75 competitions.
Also known as bartokulus/openfoot-mcp
- Stars
- 0
- Tools
- 12
- Downloads, 30 days
- —
- Latest version
- 0.1.2
- Last commit
- Sep 7, 2026
- License
- MIT
What is OpenFootAPI MCP?
OpenFootAPI provides an AI client with real-time football data including fixtures, standings, lineups, live events, and shot-level xG across 75 competitions. It exposes 12 tools, such as openfoot_competitions, openfoot_search, openfoot_matches.
Summary generated from the project's README
About OpenFootAPI MCP server
Accessing real-time football intelligence through an AI client is what this server enables for developers and analysts. It provides precise data across 75 competitions, including fixtures, standings, lineups, and live match events. Unlike general models that might hallucinate scores, this server delivers factual information such as shot-level expected goals with pitch coordinates and model-derived fair odds.
Users connect to the OpenFootAPI by setting an OPENFOOT_API_KEY in their environment variables. The server runs via npx and is compatible with Claude Desktop, Claude Code, Cursor, and Windsurf. It offers 15 specific tools, including openfoot_search for resolving team IDs and openfoot_match_xg for detailed shot analysis.
A free tier provides 5,000 requests per month with a limit of 60 requests per minute. The server includes a quota tool to monitor remaining usage and a health tool to check connectivity. Developers should use openfoot_competitions to verify data depth before building, as coverage varies between leagues like the Bundesliga and the Premier League.
What you can do with it
- 1Analyze team performance trendsAsk the AI to evaluate a team's recent form by looking at their last five matches and the underlying expected goals.
Written from the project's README. Every use case is checked against a quote from it.
How to install OpenFootAPI MCP
Formats verified 10 Nov 2026Add to CursorAdd to GooseInstall OpenFootAPI MCP in Claude Code
$ claude mcp add --env 'OPENFOOT_API_KEY=<YOUR_OPENFOOT_API_KEY>' openfoot-mcp -- npx -y openfoot-mcpInstall OpenFootAPI MCP in Cursor
~/.cursor/mcp.json
{
"mcpServers": {
"openfoot-mcp": {
"command": "npx",
"args": [
"-y",
"openfoot-mcp"
],
"env": {
"OPENFOOT_API_KEY": "<YOUR_OPENFOOT_API_KEY>"
}
}
}
}Install OpenFootAPI MCP in VS Code
.vscode/mcp.json
{
"servers": {
"openfoot-mcp": {
"type": "stdio",
"command": "npx",
"args": [
"-y",
"openfoot-mcp"
],
"env": {
"OPENFOOT_API_KEY": "<YOUR_OPENFOOT_API_KEY>"
}
}
}
}Install OpenFootAPI MCP in VS Code CLI
$ code --add-mcp '{"name":"openfoot-mcp","type":"stdio","command":"npx","args":["-y","openfoot-mcp"],"env":{"OPENFOOT_API_KEY":"<YOUR_OPENFOOT_API_KEY>"}}'Install OpenFootAPI MCP in Claude Desktop
claude_desktop_config.json
{
"mcpServers": {
"openfoot-mcp": {
"command": "npx",
"args": [
"-y",
"openfoot-mcp"
],
"env": {
"OPENFOOT_API_KEY": "<YOUR_OPENFOOT_API_KEY>"
}
}
}
}Install OpenFootAPI MCP in Codex
$ codex mcp add openfoot-mcp --env 'OPENFOOT_API_KEY=<YOUR_OPENFOOT_API_KEY>' -- npx -y openfoot-mcpInstall OpenFootAPI MCP in Codex config.toml
~/.codex/config.toml
[mcp_servers.openfoot-mcp] command = "npx" args = ["-y", "openfoot-mcp"] [mcp_servers.openfoot-mcp.env] OPENFOOT_API_KEY = "<YOUR_OPENFOOT_API_KEY>"
Install OpenFootAPI MCP in Gemini CLI
$ gemini mcp add -s user -e 'OPENFOOT_API_KEY=<YOUR_OPENFOOT_API_KEY>' openfoot-mcp npx -- -y openfoot-mcpInstall OpenFootAPI MCP in Gemini settings.json
~/.gemini/settings.json
{
"mcpServers": {
"openfoot-mcp": {
"command": "npx",
"args": [
"-y",
"openfoot-mcp"
],
"env": {
"OPENFOOT_API_KEY": "<YOUR_OPENFOOT_API_KEY>"
}
}
}
}OpenFootAPI MCP tools 12
Detected from the READMEopenfoot_competitionsopenfoot_searchopenfoot_matchesopenfoot_standingsopenfoot_match_lineupsopenfoot_match_eventsopenfoot_match_xgopenfoot_match_contextopenfoot_league_xgopenfoot_oddsopenfoot_quotaopenfoot_health
| openfoot_competitions | — | |
| openfoot_search | — | |
| openfoot_matches | — | |
| openfoot_standings | — | |
| openfoot_match_lineups | — | |
| openfoot_match_events | — | |
| openfoot_match_xg | — | |
| openfoot_match_context | — | |
| openfoot_league_xg | — | |
| openfoot_odds | — | |
| openfoot_quota | — | |
| openfoot_health | — |
Configuration
OPENFOOT_API_KEYRequiredSecretOpenFoot API key. Free tier at https://openfootapi.com/pricing
| Name | Description | |
|---|---|---|
| OPENFOOT_API_KEY | OpenFoot API key. Free tier at https://openfootapi.com/pricing | RequiredSecret |
Automated checks
Ran Nov 14, 2026Full report →Passed our automated checks. That is not a security audit: read the code and give the server the narrowest access it needs. How checks work
- Source repository linked and reachablebartokulus/openfoot-mcp is public and reachablegithub.com/bartokulus/openfoot-mcp ↗Pass
- Package names this repository as its sourceopenfoot-mcp names bartokulus/openfoot-mcp as sourcenpmjs.com/package/openfoot-mcp ↗Pass
- Build provenance (Sigstore attestation)No build attestation published for this releaseNot checked
- Open source license (OSI)MITspdx.org/licenses/MIT.html ↗Pass
- Commit or release in the last yearLast commit or release 2026-09-07github.com/bartokulus/openfoot-mcp ↗Pass
- OpenSSF ScorecardNot checked
- Package name not close to a popular packageNo popular package one edit away from openfoot-mcpPass
- No critical advisory in the package or its dependencies99 resolved dependencies checked; no critical advisoryosv.dev ↗Pass
- No hidden instructions to the model12 tool descriptions and the README read; no override phrases, credential paths or hidden charactersPass
- Destructive tools are labelledNo tool named like delete, drop or execPass
- Remote endpoint answers the MCP handshakeNot checked
README
View on GitHubopenfoot-mcp
MCP server for the OpenFootAPI football intelligence 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.
15 tools, 1 prompt. Node ≥ 20, no build step.
Install
npx openfoot-mcp
Set your API key in the environment. Free tier: 5,000 requests/month. Get a key at openfootapi.com/pricing.
Claude Desktop / Claude Code
{
"mcpServers": {
"openfoot": {
"command": "npx",
"args": ["-y", "openfoot-mcp"],
"env": { "OPENFOOT_API_KEY": "of_live_..." }
}
}
}
Cursor / Windsurf / any stdio MCP client
Same block, in that client's MCP config file.
Tools
| Tool | What it returns |
|---|---|
openfoot_competitions |
Supported competitions, season metadata, data source and licence per competition |
openfoot_search |
Free-text team/competition name → stable IDs |
openfoot_matches |
Fixtures and results, filtered by date / competition / team / status / season / round, cursor-paginated |
openfoot_standings |
Standings table for a competition and season |
openfoot_match_lineups |
Starting XI, bench, formation |
openfoot_match_events |
Goals, cards, substitutions, commentary timeline |
openfoot_match_xg |
One entry per shot: pitch coordinates + xG value |
openfoot_match_context |
Derived context — form, head-to-head, pre-computed signals |
openfoot_league_xg |
League xG table: xG for, xG against, over/under-performance vs actual goals |
openfoot_odds |
Bookmaker benchmark + implied fair probabilities. Informational, not betting advice |
openfoot_quota |
Remaining monthly quota — this call does not consume quota |
openfoot_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 openfoot_search to resolve IDs. Guessing IDs wastes quota: 404s and empty results are metered like any other request.
Coverage, stated honestly
The catalogue lists 120 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 openfoot_competitions and check your league before you build on it.
Quota behaviour
- Free: 5,000 requests/month, 60 req/min. Developer $14/month: 250,000 requests/month, 100 req/min, includes xG, shot maps, lineups, live events and fair odds. Pro $39/month: 2,000,000/month, 250 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 health
npm run smoke works without an API key: openfoot_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.
OpenFootAPI MCP questions
How do I add OpenFootAPI MCP to Claude Code?
Run claude mcp add --env 'OPENFOOT_API_KEY=<YOUR_OPENFOOT_API_KEY>' openfoot-mcp -- npx -y openfoot-mcp in your terminal. Add --scope user to make it available in every project.
How do I add OpenFootAPI MCP to Cursor?
Open ~/.cursor/mcp.json and add the server under mcpServers, using the Cursor config shown in the install section above.
What tools does OpenFootAPI MCP provide?
It exposes 12 tools, including openfoot_competitions, openfoot_search, openfoot_matches, openfoot_standings, openfoot_match_lineups.
How much does the free tier allow?
The free tier provides 5,000 requests per month.
What happens when I exceed my monthly quota?
There is no overage billing; instead, the API returns a 429 error which the server surfaces as a quota or rate limit error.
Does the server work without an API key?
Yes, the health check tool works without a key to verify reachability.
Which football leagues have the deepest coverage?
The deepest coverage is available for Bundesliga, 2. Bundesliga, DFB Pokal, and Superliga României.