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 match details, live fixtures, and league top stats
• MCP resources for route reference and reusable prompt context
• Optional 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. Fresh by default.
search_fotmob	Query FotMob search suggestions.
get_match_details	Fetch match details from a FotMob match id or URL. Fresh by default.
get_match_liveticker	Fetch match live ticker/commentary events from a match id or URL. Fresh by default.
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_liveticker	/api/data/ltc
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.

For match pages, prefer get_match_details when you have a FotMob URL:

get_match_details("https://www.fotmob.com/en-GB/matches/japan-vs-brazil/1uqadm#4653711")

For match commentary/live ticker events, use the same URL or match id:

get_match_liveticker("https://www.fotmob.com/en-GB/matches/japan-vs-brazil/1uqadm#4653711")

The match page slug can vary; the helper extracts the match id from the URL fragment. If FotMob has no live ticker file for a match, the tool returns status: unavailable with an empty events array.

All MCP tools fetch fresh FotMob data by default, including search, league, team, player, match, fixture, heatmap, transfer, TV, audio, and provider routes. fetch_fotmob_route and get_match_details still expose use_cache=true for explicit opt-in caching.

Configuration

Optional environment variables:

Variable	Description
FOTMOB_BASE_URL	Override the default FotMob base URL.
FOTMOB_CACHE_DIR	Change the local cache directory for explicit cache use.
FOTMOB_CACHE_TTL_SECONDS	Change cache lifetime in seconds for explicit cache use.
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