FotMob MCP

Model Context Protocol server for live FotMob football data.

FotMob MCP exposes a small set of MCP tools and resources for working with football data from FotMob. It is intended for agents and local tooling that need fixture lookup, league pages, team/player data, match details, live fixture polling, and league stats.

Features

• Verified FotMob route catalog
• Search suggestions for teams, players, leagues, and matches
• Direct fetch tool for supported FotMob JSON routes
• Helpers for live fixtures and league top stats
• MCP resources for route reference and reusable prompt context
• Local response cache
• stdio, sse, and streamable-http transports

Installation

From the repository root:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt

requirements.txt installs the runtime dependencies and this package in editable mode.

Verify that the console script is available:

command -v fotmob-mcp
fotmob-mcp --help

Usage

Run the server with the default stdio transport:

fotmob-mcp

Run with streamable HTTP:

fotmob-mcp --transport streamable-http --host 127.0.0.1 --port 8000

Default streamable HTTP endpoint:

http://127.0.0.1:8000/mcp

Client Configuration

Codex

codex mcp add fotmob -- fotmob-mcp

Hermes Agent

Install the package in the runtime environment used by Hermes, then add the MCP server entry:

{
  "mcpServers": {
    "fotmob": {
      "command": "fotmob-mcp",
      "args": []
    }
  }
}

Verify that Hermes can resolve the command from the same environment:

command -v fotmob-mcp

Tools

Tool	Description
list_fotmob_routes	List supported routes, optionally filtered by keyword.
fetch_fotmob_route	Fetch a supported route by route key and JSON parameters.
search_fotmob	Query FotMob search suggestions.
get_live_fixtures	Fetch live fixtures from a league payload's poll link.
get_league_top_stats	Fetch league player or team stats and resolve internal season ids when possible.

Resources

Resource	Description
fotmob://reference	Markdown reference for the supported FotMob API routes.
fotmob://routes	Route catalog generated by the server.
fotmob://prompt	Reusable prompt context for agents.

Supported Routes

Key	Endpoint
search_suggest	/api/data/search/suggest
all_leagues	/api/data/allLeagues
matches	/api/data/matches
leagues	/api/data/leagues
leagues_shotmap	/api/data/leagues?shotmap=true
league_season_deep_stats	/api/data/leagueseasondeepstats
teams	/api/data/teams
player_data	/api/data/playerData
player_matches	/api/data/playerMatches
match_details	/api/data/matchDetails
match_heatmaps	/api/data/heatmap/match/{matchId}/heatmaps
transfers	/api/data/transfers
tvlistings	/api/data/tvlistings
audio_matches	/api/data/audio-matches
dataproviders	/api/data/dataproviders

Use list_fotmob_routes to inspect parameters and notes for each route.

Configuration

Optional environment variables:

Variable	Description
FOTMOB_BASE_URL	Override the default FotMob base URL.
FOTMOB_CACHE_DIR	Change the local cache directory.
FOTMOB_CACHE_TTL_SECONDS	Change cache lifetime in seconds.
FOTMOB_MCP_TRANSPORT	Default transport: stdio, sse, or streamable-http.
FOTMOB_MCP_HOST	HTTP bind host.
FOTMOB_MCP_PORT	HTTP bind port.
FOTMOB_MCP_SSE_PATH	SSE endpoint path.
FOTMOB_MCP_STREAMABLE_HTTP_PATH	Streamable HTTP endpoint path.

Development

Run tests:

python -m unittest