内容
# FotMob MCP
用于提供 FotMob 足球比赛实时数据的模型上下文协议（MCP）服务器。
FotMob MCP 提供了少量 MCP 工具和资源，用于处理 FotMob 的足球比赛数据。它适用于需要比赛查询、联赛页面、球队/球员数据、比赛详情、实时比赛轮询和联赛统计数据的代理和本地工具。
## 功能特点
- 验证过的 FotMob 路线目录
- 球队、球员、联赛和比赛的搜索建议
- 支持的 FotMob JSON 路线的直接获取工具
- 实时比赛详情、实时比赛和联赛最佳统计数据的帮助程序
- 路线参考和可重用的提示上下文的 MCP 资源
- 可选的本地响应缓存
- `stdio`、`sse` 和 `streamable-http` 传输方式
## 安装
从存储库根目录：
```bash
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -r requirements.txt
```
`requirements.txt` 安装运行时依赖项和此软件包（以可编辑模式）。
验证控制台脚本是否可用：
```bash
command -v fotmob-mcp
fotmob-mcp --help
```
## 使用
使用默认的 stdio 传输方式运行服务器：
```bash
fotmob-mcp
```
使用可流式 HTTP 运行：
```bash
fotmob-mcp --transport streamable-http --host 127.0.0.1 --port 8000
```
默认的可流式 HTTP 端点：
```text
http://127.0.0.1:8000/mcp
```
## 客户端配置
### Codex
```bash
codex mcp add fotmob -- fotmob-mcp
```
### Hermes 代理
在 Hermes 使用的运行时环境中安装软件包，然后添加 MCP 服务器条目：
```json
{
"mcpServers": {
"fotmob": {
"command": "fotmob-mcp",
"args": []
}
}
}
```
验证 Hermes 是否可以从同一环境解析命令：
```bash
command -v fotmob-mcp
```
## 工具
| 工具名称 | 描述 |
| ------------------------- | -------------------------------------------------------------------------------- |
| `list_fotmob_routes` | 列出支持的路线，可选地按关键词过滤。 |
| `fetch_fotmob_route` | 通过路线键和 JSON 参数获取支持的路线。默认情况下是新鲜的。 |
| `search_fotmob` | 查询 FotMob 搜索建议。 |
| `get_match_details` | 从 FotMob 比赛 ID 或 URL 获取比赛详情。默认情况下是新鲜的。 |
| `get_match_liveticker` | 从比赛 ID 或 URL 获取比赛实时记分板/评论事件。默认情况下是新鲜的。 |
| `get_live_fixtures` | 从联赛 payload 的轮询链接获取实时比赛。 |
| `get_league_top_stats` | 获取联赛球员或球队统计数据，并在可能的情况下解析内部赛季 ID。 |
## 资源
| 资源名称 | 描述 |
| ---------------------- | ------------------------------------------------------- |
| `fotmob://reference` | 支持的 FotMob API 路线的 Markdown 参考。 |
| `fotmob://routes` | 由服务器生成的路线目录。 |
| `fotmob://prompt` | 代理的可重用提示上下文。 |
## 支持的路线
| 键值 | 端点 |
| ------------------------- | ---------------------------------------- |
| `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` |
使用 `list_fotmob_routes` 检查每个路线的参数和备注。
对于比赛页面，如果您有 FotMob URL，请优先使用 `get_match_details`：
```text
get_match_details("https://www.fotmob.com/en-GB/matches/japan-vs-brazil/1uqadm#4653711")
```
对于比赛评论/实时记分板事件，请使用相同的 URL 或比赛 ID：
```text
get_match_liveticker("https://www.fotmob.com/en-GB/matches/japan-vs-brazil/1uqadm#4653711")
```
比赛页面 slug 可以变化；帮助程序从 URL 片段中提取比赛 ID。如果 FotMob 没有比赛的实时记分板文件，工具将返回 `status: unavailable` 和空的 `events` 数组。
所有 MCP 工具默认获取新鲜的 FotMob 数据，包括搜索、联赛、球队、球员、比赛、比赛轮询、热图、转会、电视、音频和提供商路线。`fetch_fotmob_route` 和 `get_match_details` 仍然为显式选择加入缓存公开 `use_cache=true`。
## 配置
可选环境变量：
| 变量名称 | 描述 |
| --------------------------------- | ------------------------------------------------------- |
| `FOTMOB_BASE_URL` | 覆盖默认的 FotMob 基本 URL。 |
| `FOTMOB_CACHE_DIR` | 更改显式缓存使用的本地缓存目录。 |
| `FOTMOB_CACHE_TTL_SECONDS` | 更改显式缓存使用的缓存生命周期（秒）。 |
| `FOTMOB_MCP_TRANSPORT` | 默认传输方式：`stdio`、`sse` 或 `streamable-http`。 |
| `FOTMOB_MCP_HOST` | HTTP 绑定主机。 |
| `FOTMOB_MCP_PORT` | HTTP 绑定端口。 |
| `FOTMOB_MCP_SSE_PATH` | SSE 端点路径。 |
| `FOTMOB_MCP_STREAMABLE_HTTP_PATH` | 可流式 HTTP 端点路径。 |
## 开发
运行测试：
```bash
python -m unittest
```
