Content
# 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:
```bash
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:
```bash
command -v fotmob-mcp
fotmob-mcp --help
```
## Usage
Run the server with the default stdio transport:
```bash
fotmob-mcp
```
Run with streamable HTTP:
```bash
fotmob-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```
Default streamable HTTP endpoint:
```text
http://127.0.0.1:8000/mcp
```
## Client Configuration
### Codex
```bash
codex mcp add fotmob -- fotmob-mcp
```
### Hermes Agent
Install the package in the runtime environment used by Hermes, then add the MCP server entry:
```json
{
"mcpServers": {
"fotmob": {
"command": "fotmob-mcp",
"args": []
}
}
}
```
Verify that Hermes can resolve the command from the same environment:
```bash
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:
```text
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:
```text
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:
```bash
python -m unittest
```
