![FotMob MCP banner](assets/fotmob-mcp-banner.png)

# FotMob MCP

Model Context Protocol server for live FotMob football data.

![Python 3.11+](https://img.shields.io/badge/python-3.11%2B-3776AB?style=flat-square&logo=python&logoColor=white)
![MCP ready](https://img.shields.io/badge/MCP-ready-16A34A?style=flat-square)
![Transports](https://img.shields.io/badge/transports-stdio%20%7C%20SSE%20%7C%20HTTP-0F766E?style=flat-square)

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
```